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This document is for process control software engineers who wish co wriceapplicarion pro- 
grams co run on che I/A Series System. 

Readers are assumed co know che C or FORTRAN programming languages. They are also 
assumed co be familiar wich che VENDC (or UNIX) operating system. 
I/A Series reference Documents: 

SunOS Reference Manual I, II, III (BO 1 93LC) 

VENDC User Reference Manual (BO 1 93 BV) 

VENIX Programmer's Reference Manual (BO 1 93 BX) 

VENDC Administrators Reference Manual (BO 1 93 BW) 

VENDCSupport Tools Guide (BO 1 93CA) 

50 Series Program Development (BO 1 93 LQ) — 
Program Development VENIX (BO 1 93BA) 
Inter-Process Communications Calls (B01933B) 
Human Interface Calls (B0193BD) 
• Miscellaneous Calls (B0195BE) 
Supervisory Setpoint Control (BO 1 93 RY) 
System Messages (BO 1 93CG) 

Revision Information 

The following changes were made for Release 4.2: 

All calls in each Section were listed alphabecicaily. Added an incroduction to each Section 
which lists the calls in che Section. 

Section 1. Object Manager Concepts 

♦ Added CP40 co Objecc Manager Paramecer Table. 
Section 2. C Calls co Get/Sec Objecc Values 

♦ Added che following new calls: 

♦ sc_serval. sc_seccnf, sc_om_secval, sc_omser_confirm, 
sc_scc_lisc and sc_sedisc_confirm. 

♦ Modified che daca cype and recurn code descripcions for che sec- 
val, sec_conftrm, om_secval, om_scc_confirm, secvaljisc and 
sec_confirm_!isc. 

♦ Changed call sec_confirm_Iisc co sec_cnf_lisc. 
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♦ Deleted return codes: NOT_S ETTAB LE, SECURED, 
TO_REAL_CONV_ERROR, 
TOJiNTEGER_CONV_ERROR, 
TO_STRING_CONV_ERROR, 
TO r BOOL_CONV_ERROR, from serval, se:_confirm, 
om_sctval, om.set.confirm, setvaljist and se:_cnf_lisc. 

J Section 5. C Calls to Access Update Sets of Variable 

I ♦ Added the new call: omwrstat. 

♦ Changed die value structure descriptions for "index" and 
"value 0 in the o rewrite call. 

♦ Added EWRITERROR return codes and changed return code 
descriptions for omwritc call. 

Section 5. FORTRAN Function to Get/Set Object Values 

♦ Added command strong to compile FORTRAN programs. 
Appendix B. OM Error Codes 

♦ Added OM Error Codes, Appendix B." 
Appendix C. OiM Calls 

♦ Added OM C Calls 

♦ Added OM FORTRAN Calls 



viii. 



■■■■■r ■ 

K > 



7. Object Manager. Concepts 



An object is a construct that the Object Manager can find by name, relieving you of the need 
co know its location or path name. The operating system automatically declares process vari- 
aolcs, Iettcrbug names, and device logical names co be objects. Object Manager calls let you 
create and delete object names and read and write (get and set) object values. 1 
Some of the Object Manager calls chemselvcs invoke calls from other subsystems. When this 
happens, some rccum codes mighc actually come from che ocher subsyscem. The exact code is 

passed back to the calling task whenever possible, and the explanations are included with each 
call. 

The Object Manager supports two kinds of objects: shared objects and process-concrol 
objects. Their characteristics are given below. 



Shared Objects Variables 


Control Objects or Process j 


14 character name (maximum) 


32 character name | 


You can create, delete, read and 
wrice shared objects 


You can only read and write control objects 


Can be of all object types 


Can only be of object type VARIABLE 



1 .1 Object and Data Types 

An object can have one of che following* types: 



♦ VARIABLE 

♦ ALIAS 

♦ DEVICE/ 



LETTERBUG 
PROCESS 



A shared and process (concrol compound) variable 

An objecc whose value is the name or another objecc 

The lecterbug id or logical name of an external device like a sta- 
tion or printer 

A program in execution; a task 

The regular shared VARIABLE objecc type can have any of che following daca cypes: 
CHARACTER 
INTEGER 
FLOAT 
STRING 

OM.BOOL (characcer, values = cruc. false) 
OM_LNG_INT (long integer) 

♦ OM_S_PKBOL (packed boolean) 

♦ OM_L_PKBOL (long packed boolean) 

An ALIAS objecc cype can only have STRING daca cype. 



♦ 

♦ 
♦ 
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The object types DEVICE and PROCESS are cypialiy, buc noc always, used with global Jind 
co get chc address of die scadon where die device or cask is residenc. Since die object cypes 
DEVICE/LETTERBUG and PROCESS do noc have values, die/ cannoc have any data r/pes. 
The Object Manager does noc restrict chc daca type of concrol objects (VARIABLE object 
type); chey can be of any daca cype allowed by die control software. 

Incegers are signed, unless die block parameter definition specifies otherwise. Reals adhere co 
die IEEE standard. 

The data types are stored in die status word of each object's value record structure. 

You have to make sure thac die ipch include file is available, as chc Object Manager include 

file "includes" itas*well. 

1 .2 Object Names — 

The maximum length for shared object names is 14 characters. Only alphanumeric* and the 
underscore are permitted for types variable and alias. Types device and process can use any 
character. Duplicate object names are permitted only if they are of different object types. 
Control objects (process variables) and device names are exceptions. The Object Manager 
does not restrict them, although their respective configurators do. Process variables can have 
names up to 32 characters to accommodate the compound, block, and parameter names. 
Refer to the Integrated Control Configurator and System Configurator documents for more 
information on these names. 

The complete OM name used to get ECB configuration and measurement parameters has the 
following format: 

<letrerbug>_SC3:<eBM_ID>.<I/A_nanie> - . 

where letterbug is replaced with the letterbug of the Tank Processor, FSMJD is replaced with 
the HIU letterbug, and l/A_name is the parameter name. 

Example: To get the pressure transmitter 1 frequency of a HIU with the letterbug of 

HTG131, which is connected to a Tank Processor with the letterbug of 
TP1013, the complete OM variable name is 
TP1013_ECB:HTG131.C105. ■ _ 
All parameters that begin with- BYT are character arrays. All parameters that begin with 
NAME are character arrays. All other parameters are floating point numbers. Refer to the 
control documents for parameter names. Names in OM open list should be uppercase. 

1 .3 The Import List and the Object Directory 

The import list contains the names of objects from ocher stations. Listed with each name is 
an index to its address in the address cable. This list lees che Object Manager find objects with 
ouc sending ouc a broadcast co locace objects in remoce stations. Objects are added to the list 
• as che resulc of user requests. 
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If you arc no c going co gee an object many rimes in a program, you are bearer off not bother- 
ing co import it. There is only one import Use for che scacion, and all tasb have co share it, so 
for efficiency, you should unimport all objects when you exit. 

The get/set calls can import objects as specified. The object directory contains all che shared 
objects created by tasks in the local station. They automatically become globally known when 
you create them. The object directory contains pointers to the objects' values, if any. 

NOTE: You must close all OM lists before any exit from the program occurs. 

1.4 Variable Scan Rates 

The Object Manager lets you specify a scan rate for change-driven lists. This variable scan 
rate is che rate at which the station that is the source of the data sends updates to che scacion 
chac opened che list. If you have programs written before variable scan rates were available, 
you should change your code to select the appropriate scan rate. - 

You must specify che scan rate for an OMOPEN list in the om _header_node structure in a 
C program. It is in intervals of 1/2 second. A value of one causes a scan rate of 1/2 second, a 
value of four a scan rate of 2 seconds, and so on. 

The range of valid scan rates is from 1/2 second to 120 seconds. An invalid scan rate is forced 
co the default value of 1/2 second. 

The following example is user code setting the scan rate to 10 seconds before performing the 
OMOP£N request. 



# define SCAN_CYCLES 20 

struct om_header_node *hdr_ptr; 

hdrjptr = (struct ora_header_noce*) 

iaalloc { size of struct orn_header_ncds) ; 
if ('hdrjptr != (struct omjieaderjioca* ) NULL ) - 
{ 

/* Set up for omopen. */ 
hdrjptr->scan_rate = SCAN_CYCL£5; 



/* Perform OMOPEN. */ 

] 

else 

The FORTRAN format is as specified later for OMOPEN 
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bncf explanation of each item in che able follows che cable. 




__*12 for WP20 and CP 10, 30 for WP50 and CP30/CP40. 
"50 for-CPlO, 150 for CP30, 600 for CP40. 
~5 for CP10, 10 for CP30/CP40. 
#V3.I release on 50 Series maximums ire configurable 

Some k<ims are subject to constraints from other sub-systems (the number of connections or 
the number of points scanned, for example) .. 

OMOPEN Lists The maximum number of change-driven omopen lists. 

Points per List The maximum number of change-driven points for one omopen list. 

Shared Objects The maximum number of shared objects that can exist in a station at one 
time.. 

Imported Objects The maximum, number of objects that can be in an import list at one rime. 

Scanner Entries The number of scanner entries chat one station can scan. Each en cry corre- 
sponds to (part of) a list and can contain up to 20 poincs. The actual num- 
ber of points a stacion can scan depends on the number of omopen Uses 
and the size of each list. How many scanner en cries arc used for an 
omopen list is computed as follows: 

entries = (# poincs in scarion for lisc +1 9)/20 

50 Scries stations are an exception and concain up co 255 poincs per entry 
and chcrcfore have a one co one relationship between a lisc and scanner 
en cry. 

Example: 

A WP20 opens a lisc for 86 poincs chac has 40 poincs in CP I, 45 points in CP2. and 1 point 
inCP3. 

CP I scanner entries = (40+19.V20 = 2 
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CP2 scanner entries = (45+19)/20 = 3 

CP3 scanner encries = (l+19)/20 = 1 

For 50 Series = 1 entry per list 
GETVAL Timeout 

The number of seconds the Object Manager waits to receive data on a 
GETVAL request. If the object does not exist, the requester suspends for 
12 seconds. 

SET^CONFIRMTimcoiK 

The number of seconds the Object Manager waics to get a reply co a 
SET_CONFIRM request. If the stadon wich the object is down, the 
requester suspends for 12 seconds. 

CHANGE Queues • " 

The number of queues available for open lists that want notification of 
changes. These queues are based on chc process id in a particular s radon 

1 .6 Object Manager Databases 

The databases of the Object Manager for 50 Series reside in shared memory. This memory is 
divided into three partirions. The first partition is static and contains the static tables. The 
second partition is a valloc pool for open lists. The third partition is another valloc pool ded- 
icated to strings created for shared objects (see Figure 1-1 and Figure 1-2). 
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Figure 1-1. Object Manager Software Components 
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Figure 1-2. Object Manager Software Components (Cont.) 

1.6.1 Open Points Database 

The open points database is a linked list of descriptors (or header nodes) which describes lists 
of objects opened in this station. This database is further split into two portions: Remote 
Lists — those opened from remote starions, and Local Lists - those opened "by applications 
locally. Remote Lists do not have a Network Address Table. 

Separate locks (read and write) are maintained for each of the two' portions. Since the Object 
Manager server operates (and locks) primarily on the Remote portion of the database, it does 
not usually interfere with user processes which access primarily the Local portion. As men- . 
tioned above, the lists are valloced from one distinct partition. 

1 .6.2 Scanner Database 

The scanner database is an indicator of which objects in an open lis: are co be scanned. All 
Remoce Lists thac are not opened for write <7rc/y access, are scanned. Objects in Local Lists are 
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scanned only if chey arc local (created in cfais sacion). Single connec: concrol variables are 
only scanned once. Deleted objects in lists are skipped, after notification has been sent. 
The number of variable record pointers that can be contained in a row of the database (which 
corresponds to one list exactly), is equal to the maximum number of objects in a list (currently • 
255). 7 



list ptr 


open var 
ptr 


open var * 
ptr 




open var 
ptr 













1.6.3 Object Directory 

The object directory contains the name of che shared object, che export stacus, r and the 
pointer to the dynamically allocated value record (as described above, from a separate shared 
memory partition). Process names and device names have null value_rec poincers. A read 
lock and a write lock synchronizes .access. 



entry 




count 




name[] 


export 


value record ptr 




status 











1.6.4 Irnpo# Table 

The import cable stores variable names with indices co the Object Manager network address 
table. A read lock and a write lock synchronizes access. 



j -entry 




j count 





| network address index 



1 .6.5 Object Manager Network Address Table 

This table is an array of network addresses poinced co by che imporc lisc and che object dire: 
tory value records. A read lock and a wrice lock synchronizes access. 

4 



i PSAP 



user count 
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1 .6.6 Scanner Connection Table 
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1 he scanner connection cable contains an array of network addresses for the connected sta- 
tions and the number of communication retrys attempted for each connection. The connect 
status flag indicates whether the connection needs to be disconnected, and whether the entry 
is needed for the creadon of a new connection. 



PSAP index 


channel id 


reference ccunt | retry count i status 













1 .6.7 Server Connection Table 

The server connection cable contains the channel id and che Primary System Address Protocol 
(PSAP address) of all remote stations. 



channel id 


PSAP 
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2. C Calls to Get/Set Object Values 

T ^'J?L?< fo 7L Ctin - S ° f Ktd " S (WrMnS) °* et V5lue - * """Unless calk ' 

tney arc best suited for sttuanons in which you only want a single transfer of data. 

*t d0CUmen ^ <=— C* connecdonless calls arc calls 

auc transfer data between tasits without having established an IPC connection (channel) first 

r^XutT" **" y ° Ur "* COOnKdonl « Y=u do not have 

iSS&t xaoiftr obira ^ ire liitcd in ^ secdon ' 



Table 2-1. C calb to Get/Sec Object Values 



Paragraph 






No. 

2.1 


Call 

gecval 


Function 


2.2 


gecvaljisc 


Gee che value of an objecc 
Gee che value of an object 


2.3 


om_gecval 


. Gee che value of an objecc 


2.4 


om sec confirm 


Sec che value o f an objec: 


2.5 


om_serval 


Sec che value of an objecc 


2.6 


set_confirm 


Sec che value of an objecc 




*ec_cnfjisc 


Sec che value of an objecc 


2.8 


secval 


Sec che value of an objecc 


2.9 


secvaljise 


Sec che value of an objecc 


2.10 


sc_o msec_co n fi rm 


Sec che value and/or seacus of an object 


2. 1 1 


se_om_secval j 


Sec che value and/or seacus of an objecc 


.2.12 


sc_seccnf | 


Sec che value and/or seacus of an objecc 


2.13 


st_scelise_confirm | 


Sec che value and/or seacus of an object ~ j 


2.14 


g-seejisc | 


Sec che value and/or seacus of an objecc | 


2.15 


sc_secval j 


Sec che value and/or seacus of an objece * | 
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2.1 getval - Get the Value of an Object 

getval*zxs the value of die specified object- An object is identified by its name and type. The 
object name can be cither a shared object name or a compound name. If che object name is a 
compound name, chen che object cype muse be variable. If che object name is a shared object 
name, chen object types can be eicher variable or alias. Object cype shared variables can be 
data types character, inceger, long integer, float, string, boolean, packed boolean, and long 
packed boolean. Object cype alias has a daca cype string. There is no daca value record for 
object types process and device, getval 'is synchronous; it suspends your cask until the transfer 
is complete. 

Format: 

int getval (<name>, <obj_type>, <i:tiport>, <value>, <sUwUs> l data_len>} 
char *nasie, * value; 

-nt obj_type, import, * dataller.; 

unsigned int *scatus; 



Where: 
*name — 
obj_type 
import 

* value 

* status 



A character pointer co the name of the object. 

The named objects type; VARIABLE or ALIAS. 

1 = place the object^ name on the import list. 
0 = do not place it on the import list. 

A pointer to che location where the Object Manager is co put che objects 
value. Specify its size in bytes using dataller.. 

A pointer to the location where the Object Manager is to return the 
objects status (data type). An ALIAS object cype can only have STRING 
daca cype. 

The regular shared VARIABLE object cype can have a data type of CHAR- 
ACTER, INTEGER, FLOAT, STRING, OM_BOOL, OMJLNGJNT 
(long inceger), OM_S _PKBOL (packed boolean), or OMJLJPKBOL 
(long packed boolean). 

The Object Manager does noc restrict process VARIABLE data types, but 
they can be of types CHARACTER, INTEGER, REAL, STRING, 
OM_BOOL (boolean), and LONG JNT and POINTER (boch long ince- 
ger). 

Incegers are signed, unless che block parameter definition specifies other- 
wise. Reals adhere co che IEEE standard. 

*cata_len A pointer to the length (bytes) allocated for value. OM returns actual 



Return Codes: 
"OM_SUCCESS 
ENOTrOCJND 



length. 



No errors. 

Object not found (locally or globally). 
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ESADTYPS 
ENOSPACZ 
E3A0NAMZ 
E3ADLEN 
ENOVAME 
E3ADVHEC 
EIPCRZT 
TO_BIG 
.Call Notes: 
1 



Illegal object cype. 

No memory available; no value returned. 
Invalid object name. 
Shared variable is too big for data_len. 
Specified object cype has no "value". 
"Value* is corrupt, invalid dara cype. 
You have an unspecified IPC error. 
Process variable is coo big for data_len. 



Placing a local object-(one found in the same starion) on the import list is unnec- 
essary, so for local objects getval ignores that option. However, the value is still 
returned. 

2. If you get an error return, the Object Manager may still return a value, but it is 
garbage. Do not send the returned value co useful data areas unless there is no error 
return. _ * 

3. Return code ENOTFOUND mighc mean chat the object docs not exist locally or 
globally. If the obj cct exists in a remote stacion, then that station might be down. 
In either case, The Object Manager removes che objects name from the import 

* list. 

4. If you do not make data_len large enough, value will be too small to hold the 
returned value. In such a case getval returns as much data in value as will fit. 

5- If data_len is too large, value will contain unused bytes, getval does not close-up 
this unused memory space. 

6. Status, data_len, and value are modified regardless of error return.. 
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22 getval Jist - Get the Value of an Object 

gevualJList gets die value of die specified object. This call is a variation of die om_getvdcsl\. It 
differs only in die way die PSAP is specified. 

Instead of die ?sa? _atz input: argument used in om_gerjaK), the getval Jisd) call uses an 
<open_id> and an <ov_incax> argument. The < open_id> argument specifies the ID of an 
open variables list. The list need not be optimized, but ic must currendy be opened. The 
<ov_inde:o specifies the index of a variable entry within the list. The variable must be con- 
nected. It is assumed that the variable in the list and the target object reside in the same sta- 
tion. (The variable and the object may or may not be one in the same.) The PSAP associated 
with that variable identifies the station to which the getval message will be sent. The message 
will not be broadcast. 

getualjistxs synchronous; it suspends your task until the transfer is complete. 
Format: 

int getval_list: (<name>, <obj_ty?e>, <import>, «value>, <status>, <data_lan>, 
<open_id>, <ov_index>) 



cnar 
int 

unsigned int 



♦name, * value; 

obj_ty?e, imporc, *data_len, cpan_id, ov.ir.dex; 
♦status; 



Where: 
*narae 
obj_type 
import: 

♦value 

*status 



* dataller. 
ocen_id 



A character pointer to the name of the object. 

The named objects type; VARIABLE or ALIAS. 

1 = place the objects name on the import list. 
0 = do not place it on the import list. 

A pointer to the location where the Object Manager is to put the objects 
value. Specify its size in bytes using datajen. 
A pointer to the location where the Object Manager is to return the 
objects status (data type). An ALIAS object type can only have STRING 
datatype. . 

The regular shared VARIABLE object type can have a data type of CHAR- 
ACTER, INTEGER, FLOAT, STRING, OMJOOL, OM_LNG_INT 
(Ion* integer), OM S J>KBOL (packed boolean), or OMJL_PKBOL 
(long packed boolean). 

The Object Manager does noc restrict process VARIABLE data types, but 
they can be of types CHARACTER, INTEGER, REAL, STRING, BOOL 
(boolean), and LONGJNT and POINlER (both long integer). 
Integers arc signed, unless the block parameter definition specifies other- 
wise. Reals adhere to the IEEE standard. 

A pointer to the length (bytes) allocated for "value." OM returns actual 
length. 

ID of an open variables list. 
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ov_incex 
Renirn Codes: 

OM_SUCCESS 
ENOTFOCJND 

E3ADTYPE 

ENOSPACE 

EHADNAME 

EBAOLEN 

ENOVALCJE 

E3ADVREC 
EIMPFULL 
E3AD INDEX 

ENCTOPENED 
ENOT ACTIVE 
EIPCRET 
Call Notes: 



Indcc of a variable en cry within chc list. 



No errors. 

The name co gee wai found in die import list, buc IPC returned an error 
which indicates che message was rejected because station may be down. 
The object name is removed from the import list. 
' Illegal obj ect type argument. 
No memory available; no value returned. 
Invalid object name. 
Shared variable is coo bis for data len. 

Specified object type has no "value!! The caller requested co get che value 
of an object type process or device. 

"Value" record is corrupt, invalid data cype. 

Import table full; valae is returned. 

The specified ov_index is out of range, or selects an entry which is not cur- 
rendy in use. - 

The specified open_id does not correspond to an open variables list. 
Not registered with IPC for connectionless service. 
You have an unspecified IPC error. 



1. Placing a local object (one found in the same station) oh the import list is unneces- 
sary, so for local objects getval_list ignores that option. However, the value is still 
returned. 

2. If you get an error return, the Object Manager may still return a value, but it is 
garbage. Do NOT send the returned value co useful data areas unless there is no 
error return), 

3. If you do not make daca_Jen large enough, value will be too small to hold the 
returned value. In such a case getval returns as much daca in value as will fie 

4. - If data Jen is too large, value will concain unused bytes, gewal^list does not close- 

up chis unused memory space. 

5. Scacus, daca_lcn, and value are modified regardless of error return. 
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23 om_getval - Get the Value of an-Object 

om^fetval*c* che value of a specified object. This call is a functional superset of che re&alQ 
call. Ic uses Primary System Address Protocol (PSAP) pointer as an additional argument If che 
pointer value is NULL, om^ewalQ behaves as a jmdQ call, and che ^WmJsage is broad- 
cast, om^etvalxs synchronous; it suspends your cask' una! die transfer is complete" 
Formac 



int om^etval{<name> i <obj.type>,<iiriDorc> # <valus> / <scatu«> <dat = i 
<?sap_ptr>) " 

char *naize t *value; 

lnt obj'-type, import, *data_lan; 

unsigned int - *status; 

PSAP-ADDR *psap_ptr; 



Where: 
*narae 
obj_ type 
import 

*value 

^status 



*data_len 
psap_ptr 

Return Codes: 
'OM_SuCCESS 



A character pointer to the name of the object. 

* The named objects type; VARIABLE, ALIAS. 

1 = place the objects name on the import list. ~~ 
0 = do not place it on the import list. 

A pointer to the location where the Object Manager is co put die objects 
value. Specify its size in bytes using dataller.. 

A pointer to the location where the^Object Manager is to return the 
objects status (data type). An ALIAS object type can only have STRING 
data type. 

T he re gular shared VARIABLE object type can have a data type of CHAR- 
ACTER, INTEGER, FLOAT, STRING, OM_BOOL, OM JLNG JNT 
(long integer), OM_S_PKBOL, n or OMJLJPKBOL. 

The Object Manager does not restrict process VARIABLE data types, but 
they can be of types CHARACTER, INTEGER, REAL, STRING, BOOL 
(boolean), and LONGJNT and POINTER (both long integer), 
OM_S_PKBOL (packed boolean), and OM_L_PKBOL (long'packed 
boolean). 

Integers are signed, unless the block parameter definition specifies other- 
wise. Reals adhere to the IEEE standard. 

A pointer co che length (bytes) allocated for valua. OM returns actual 
length. 

Pointer co che PSAP identifying che station on which che variable is found. 
A value of (PSAP_ADDR *)NULL indicates chac no PSAP has been pro- 
vided, so che scacion muse be found using a broadcast message. 



No errors. 
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ENOTFOUND 

E3ADTYPE 
. ENOSPACE 
EBADNAiMZ 
E3ADLEM 
ENOVALCJE 

E3ADVREC 
E1MPFULL 
ENOTACTIVE 
EI PCRZ7 
Call No res: 
1 



The name co gee was found in che import list, but IPC returned an error 
which indicates che message was rejected because station may be down. 
The object name is removed from che import list. 

Illegal object type argument. 

No memory available; no value returned. 

Invalid object name. 

Sharedvariable is coo bis; for daca len. 

Specified object cype has no "value". The caller requested co ge: che value 
of an object rype process or device. 

"Value" record is corrupc, invalid daca cype. 

Import cable full; value is recurned. 

Noc regiscercd with IPC for connectionless service. 

You have an unspecified IPC error. 



Placing a local object (one found in the same scarion) on che import lisc is unneces- 
sary, so for local objects om_*etval ignores chac opuon. However, che value is still 
returned. 

If you get an error return, the Object Manager may still return a value, but it is 
garbage. Do njrsend che returned value co useful daca areas unless chere is no error 
recurn. 



3. 



If you do not make data Jen large enough, value will be coo small co hold che 
recurned value. In such a case om_getval returns as much data in value as will fit. 

4. If data Jen is too large, value will contain unused bytes. om_getual does noc close- 
up chis unused memory space. 

5. Scacus, dacajen, and value are modified regardless of error recurn. 



1 ) 
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2.4 om_set_confirm - Set the Value of an Object " 

m_set_conjzrmsm che value of die specified object and waits for confirmation chat it was set 
This call is a functional superset of che set^confirm call It uses a PSAP argument to soe-ify the 
; station to which the SETVAL message is sent. Use of the argument eliminates che need to 
broadcast the SETVAL message. This call works for shared variables, process variables, and 
aliases. om_se:_confirm is synchronous; it initiates the SETVAL message and waics for a 
response before returning control co your process/cask. 
Format: 

int ora_set_conf irm«aame> # <obj_type>, <import>, <vaiue>, <status>, <da^ len> 
<?sap_ptr>) . 

ciiar *narae, * value; 

lnt obj_type, import, dataller.; 

unsigned int *status; 

PSAP.ADDR *psap_ptr; 



Where: 
*name 
cts j— type 
import 

* value 

*status 



cata_len 
*? s *P_ptr 

Return Codes: 

OM_SUCCZS3 

E3ADTYPE 



- A pointer to the name of the object. 

The named objects type; either VARIABLE or ALIAS. 

1 = Place the objects name on che import list. 

0 = Do not place the objects name on the import list. 

A pointer to the values location. Specify its size in bytes using dataller, if 
it is a string or process variable. 

A pointer to chc location where you have stored che objects data type 
(range 1-15). 

An ALIAS object type can only have STRING data type. 
The shared VARIABLE object type can have a data type of CHARAC- 
TER, INTEGER, FLOAT, STRING, OM_BOOL (byte with True/False 
values only), OMJLNGJNT (long integer), OiVLS_PKBOL (short 
packed boolean), or OM_LJ?KBOL (long packed boolean). 
The Object Manager- does not restrict process VARIABLE data cypes. All 
shared VARIABLE -daca types arc supported plus CIO_SHORT (unsigned 
character). 

The length (in bytes) allocated for "value". This is needed for STRING 
data types and all process variables (0 defeulcs to size of float). 

A pointer to the objects station PSAP address. A value of (PSAP_ADDR ") 
NULL indicaces that no PSAP has been provided (che call acts exactly che 
same as a set^confirm call). 

The set requesc has been initiated successfully. 
The specified daca cype is noc supported. 



ti 
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The specified data cype does noc match che actual data type (shared vari- 
ables only). 

For ALIAS, che data cype is noc STRING. 

For shared VARIABLE daca cype OM.BOOL, soecined value is noc 1 
(True) or 0 (False). 

Objecc name coo long. 

Process variable name wich objecc cype noc equal co VARIABLE. 

For STRING daca cype, specified string length coo long or < = 0. 

For STRING data type, specified string length longer than actual serine 
lengch. " 3 

Objecc type DEVICE or PROCESS was specified. 
Variable is secured. 
Shared variable value record bad. 
Object noc found. 

Objecc noc found in specified scacion. A station is specified by import table" 
entry, PSAP parameter, or list ID and index parameters. 

Caller not activated with IPC- 
System resource availability problem. 
IPC returned an unspecified error. 
Return Code Notes: 

1. OM error codes are negative (refer to OM_ECODE.H or Appendix B). 

2. Control and I/O (compound processor) returns positive error codes (refer to che 
document System Messages). 

Call Notes: 

1. Placing a local object (one found in che same scation) on che imporc list is unneces- 
sary, so for local objects om_set_conjirm ignores thac option. 

2. If a value is successfully set, its BAD and OOS scams bics are automatically resec. 



E3ADNAME 



ESTRLEN 



ENO VALUE 
ESECTOZ 
E3ADVREC 
ENO CONFIRM 

ENOTFOUND 

ENOTACTIVE 
ENOSPACE 
EI PC RET - 
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2.5 om_setval - Set the Value of an Object 

om^setval sets the value of chc specified object. This call Is a functional superset of die se&al 
call. Ic provides a PSAP argument to specify the station co which the 07n_serval message is to 
be sent. Use of the PSAP argument eliminates the need co broadcast the SETVAL message, 
This call works for shared variables, process variables, and aliases, om^sewal is asynchronous if 
the object is not in the local station; it initiates the 
SETVAL message and returns control to your process/ task. 
Format: 



int om_setval. (<name>, <oc j_type>, <imccrc>, <value>, <st 
<?sap_ptr>) 



acus>, <data_ler.>, 



char 
int 

unsigned int 
PSAP_AD0R 



*name, *value; 

obj_type, import, dataller.; 

♦status; 

*psa?_ptr; 



Where: ' 
*name 
obj_type 
import 

*value 

♦status 



data_len 
*?sap_ptr 

Return Codes: 

CM.SUCCZSS 

E3ADTYPE 



A pointer to the name of the object. 

The named objects type; either VARIABLE or ALIAS. 

1 = Place the objects name on the import list. 

0 = Do not place the objects name on the import list. 

A pointer to the values location. Specify its size in bytes* using caca_len if 
it is a string or process variable. 

A pointer to the location where you have stored the objecrs data type 
(range 1-15). 

An ALIAS object cype can only have STRING data type. 
The shared VARIABLE object type can have a data type of CHARAC- 
TER, INTEGER, FLOAT, STRING, OM_BOOL (byte with True/False 
values only), OM_LNG JNT (long integer), OM_SJ?KBOL (shorr 
packed boolean), or OM_L_PKBOL (long packed boolean). 
The Object Manager does not restrict process VARIABLE data types. All 
shared VARIABLE data types are supported plus CIO_SHORT-(unsigned 
character). 

The length (in bytes) allocated for "value." This is needed for STRING 
data types and all process variables (0 defaults to size of float). 

A pointer to the objects station PSAP address. A value of (PSAP_ADDR *) 
NULL indicates thac no PSAP has been provided (che call acts exactly the 
same as a setvalczll). 

The set request has been iniciaced successfully. 
The specified data type is noc supported. 
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ESTRLSN 



E3ADVREC 



The specified daca cype does noc macch'che acmal data cype (shared vari- 
ables only) . See No ce 3 . 

For ALIAS, che data cype is noc STRING. 

For shared VARIABLE daca cyp C OM L BOOL soecified value is noc 1 
(True) o r 0 (False) . See No cc 3 . 

Object name coo long. 

Process variable name wich objecr cype noc equal co VARIABLE. 

For STRING data type, specified string lengch coo long or < = 0. 

For STRING daca cype, specified string lengch longer than actual serin* 
length. See Note 3. 8 

Object cype DEVICE or PROCESS was specified. 
VARIABLE is secured. See Note 3. 
Shared variable value record bad. See Note 3. 
Return Code Notes: 

1. OM error codes are negative (refer co OM.ECODE.K or Appendix B). 

2. Concrol and I/O (compound processor) returns positive error codes (refer co che 
documcnc System Messages). 

3. 1 hese error cases are returned only if che variable is local. 
Call Notes: 

1. Since this call is asynchronous, ic cannoc wait for return codes from remote sta- 
tions. Thus all returns concerning che object co be sec can only come from che 
local station. Control variables can only be local in a Personal "Workscation fa PW- 
CorPW-FB). -' 

2. Placing a local objecc (one found in che same scation) on che import lisc is unneces- 
sary, so for local objects om_sezjal ignores that option. 

3. If a value is successfully set, its BAD and OOS status bits are automatically reset. 
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2.6 set_confirm - Set the Value of an Object 

s&^confirm sets die value of die specified objeci and waits for confirmation that it was sec. 
This call works for shared variables, process variables, and aliases, ser^confirm is synchronous; 
it initiates the SETVAL message and waits for a response before returning control to your pro- 
cess/task. 

Format; 

inc set_ confirm (<name>, <cbj_type>, <impcrc>, <value>, <sca-:us>, <dara_len>) 

char *name, # value; 

int obj_type, import, cata_len; 

unsigned iat *status; 



Where: 
*name 
obj_type 
import 

'value 

♦status 



data_len 

Return Code$:, 

OMi.SUCCESS 

E3ADTYPE 



E3 AD MAMS 



A pointer to the name of the object. 

The named objects type; cither VARIABLE or ALIAS. 

1 = Place the objects name on the import list. 

0 = Do not place the objects name on the import list. _ 

A pointer to the values location. Specify its size in bytes using data_len if 
it is a string o r p rocess variable. 

A pointer to the location where you have stored the objects data type 
(range 1-15). 

An ALIAS object type can only have STRING data type. * 
The shared VARIABLE object type can have a data type of CHARAC- 
TER, INTEGER, FLOAT, STRING, OM_BOOL (byte with True/False 
values only), OMJLNGJNT (long integer), OM_S_PKBOL (short 
packed boolean), or OM_LJ?KBOL (long packed boolean). 
The Object Manager does not restrict process VARIABLE data types. All 
shared VARIABLE daca types are supported plus CIO_SHORT (unsigned 
character) . 

The length (in bytes) allocated for a value n .This is needed for STRING 
data types and all process variables (0 defaults to size of float). 

The set request has been initiated successfully. 
The specified data'type is not supported. 

The specified data type does not match the actual data type (shared vari- 
ables only). 

For ALIAS, the data type is not STRING. 

For shared VARIABLE data type OM_BOOL, specified value is not 1 
(True) or 0 (False). 

Object name too long. 

Process variable name with object type not equal to'VARIABLE. 
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ESTRLEM 



EMO VALUE 

ZSZCVRZ 

E3ADVREC 

ENOCONFIRM 

ENOTFOUND 



For STRING data type, specified string length coo long or < = 0; 

For STRING data cype, specified string length longer than actual serin* 
length. ° 

Object cype DEVICE or PROCESS was specified. 
Variable is secured. See Note 3. 
Shared variable value record bad. 
Object not found. 

Object not found in specified scacion. A station is specified by import cable 



ENOTACTIVE 
ENOS?ACS _ 
EIPCRET 



entry, PSAP parameter, or list ID and index parameters 
Caller noc activated with IPC. 
System resource availability problem. 
IPC returned an unspecified error. 
Return Code Notes: 

1. OM error codes axe negative (refer co OM_ECODE.H or Appendix B). 

2. Control and I/O (compound processor) returns positive error codes (refer co the 
document System Messages) . 

Call Notes: " 

1. Placing a local object (one found in the same starion) on the import list is unneces- 
sary, so for local objects set^confirm ignores that option. 

2. If a value is successfully set, its BAD and OOS status bits are automatically reset. 
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2.7 set_cnfjist- Set the Value of an Object 

^77^ SeCS ^ UC ° f dlC S ? CCificd ° b ^ Ct - This CaJI is a variacion of chc am *r confirm 
call. It differs only in the way the PSAP is specified. " 

. 1 he ID of a currendy open (optimized or unoptimized) lis: and che index of a variable entry 
in che list are specified. The variable muse be cohnected. Ic is assumed chac che lis: variable and 
che target object reside in the same station. The PSAP associated with that variable identifies 
che station to which the SETVAL message is sent. set_cnfjist\s synchronous; it suspends your 
cask until the transfer is complete. 
Format: 

int sat_cnf_list (<aame>, <obj_type>, <iinporc> f <value>, <status>, <dat = i 
<open_id>,<ov_index>) ' 



•name, * value; 



char 

lnt - obj.type, import, dataJLen, open_id, ov_index; 

unsigned int *status; 



.Where: 
*narae 
°bj_type 
impure 

*value 

♦status 



data_len 

cpen_id 
ov_inde;< 
Return Codes: 
0M_SUCCZS5 
E3ADTYPE 



A pointer to tEe name of the object. 

The named objects type; either VARIABLE or ALIAS. 

1 « Place the objects name on the import list. 

0 = Do not place the objects name on die import list. 

A pointer to the values location. Specify its size in bytes using data_leri if 
it is a string or process variable. 

A pointer to che location where you have stored the objects data type 
(range 1-15). 

An ALIAS objecr type can only have STRING data type. 
The shared VARIABLE object type can have a data type of CHARAC- 
TER, INTEGER, FLOAT, STRING, OM_BOOL (byre with True/False 
values only), OMJLNGJNT (long integer), OM_SJ?KBOL (short 
packed boolean), or OMJLJPKBOL (long packed boolean). 
The Object Manager does not restrict process VARIABLE data types. All 
shared VARIABLE data types are supported plus CIO_SHORT (unsigned 
character). 

The length (in bytes) allocated for "value". This is needed for STRING 
data types and all process variables (0 defaults to size of float). 

ID of open variables list that contains the variable to set. 

Index of a variable encry within the list. 

The set request has been initiaced successfully 
The specified data cype is not supported. 



n 
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The specified daca cype does noc match che accual daca cype (shared vari- 
ables only). 

For ALIAS, che data cype is noc STRING. 

For shared VARIABLE daca cype OM.BOOL, soecified value is noc 1 
(True) orO (False). 

Objccr name coo long. 

Process variable name with objecr cype noc equal co VARIABLE. 

For STRING data cype, specified string length coo long or < = 0. 

For STRING daca cype, specified string length longer chan actual sarin* 
length. ? 

Objecc cype DEVICE or PROCESS was specified. 
Variable is secured. See Note 3. 
Shared variable value record bad. 
Object not found. 

Object noc found in specified station. A stacion is specified by import cable 
encry, PSAP parameter, or list ID and index paramecers. 

Caller noc activated wich IPC. 

System resource availability problem. 

IPC returned an unspecified error. 

Specified list not open. 

Specified index greacer than size of list. Specified index encry noc con- • 
nected. 

Return Code Notes: 

L OM error codes are negarivc (refer co OM_ECODE.H or Appendix B). 

2. Control and I/O (compound processor) rccurns positive error codes (refer co che 
do cumcnt System Messages) . 

Call Notes: 

1- Placing a local object (one found in che same stacion) on che imporc lisc is unneces- 
sary, so for local objects set^atf^list ignores chac opcion. 

2. If a value is successfully sec, ics BAD and OOS scacus bits are aucomacically reser. 



£3 AD NAME 



ESTRLSN 



ZNOVALUE 
ESSCURE 
S3ADVREC 
ENCCONFIRM 
ENOT FOUND 

ENOTACTIVE 
EMCSPACZ 
EI PC RET " 
ENCTOPENED 
E3ADINDEX 
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2.8 setval - Set the Value of an Object 



serualsczs che value of chc specified objecr. This call works for shared variables, process vari- 
ables, and aliases, setval is asynchronous if che objecr is noc in che local scarion; ic iniciaces che 
SETVAL message and recums control co your process/ cask. 
Formac 

ms setval (<r.ame>, <ob j_type>, <iHipart>, <value>, <sta~us>, <data_Ler.>) 
char *name, "value; 

obj_type, import, dataller* ; 
unsigned int "status ; 



Where: 
"name 



import 
*value 
"status 



data_len 

Return Codes: 

CM_SUCCZSS 

E3ADTYPE 



£3 AD NAME 



A pointer co che name of che object. 

The named object's type; either VARIABLE or ALIAS. * 

1 = Place che objects name on the import list. 

0 = Do not place the objects name on the import list. 

A pointer to the values location. Specify its size in bytes using data_l an if 
* it is a string or process variable. 

A pointer to the location where you have stored che objects data type 
(range 1-15). 

An ALIAS object type can only have STRING data cype. 
The shared VARIABLE object type can have a daca cype of CHARAC- 
TER, INTEGER, FLOAT, STRING, OM_BOOL (byte with True/False 
values only), OM.LNGJNT (long integer), OM_S_PKBOL (short 
packed boolean), or OM_LJ?KBOL (long packed boolean). 
The Object Manager does not restrict process VARIABLE data types. All 
shared VARIABLE data types are supported plus CIOJSHORT (unsigned 
character). 

The length (in bytes) allocated for "value". This is needed for STRING 
data types and all process variables (0 defaulcs co size of float). 

The set* request has been initiated successfully. 
The specified data type is not supported. 

The specified data type does not match the actual daca cype (shared vari- 
ables only). Sec Note 3. 

For ALIAS, che daca cype is noc STRING. 

For shared VARIABLE daca cype OM_BOOL, specified value is noc I 
(True) or 0 (False). See Noce 3. 

Object name coo long. 

Process variable name wich object cype noc equal .co VARIABLE. 



24 
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ESTRLEN For STRING data type, specified string length coo long or < = 0. 

For STRING data type, specified scring length longer than actual serin* 
length. See Note 3. ° 

enovalue Object type DEVICE or PROCESS was specified. 

SSECURE VARIABLE is secured. See Note 3. 

E3ADVREC Shared variable value record bad. See Note g. 

Return Code Notes: 

1. OM error codes are negative (refer to OM.ECODE.H or Appendix B). 

2. Control and I/O (Compound Processor) returns positive error codes (refer to the 
document System Messages). ' 

-3.1 hesc. error cases are returned only if the variable is local. 

Call Notes: " 

.1. Since chis call is asynchronous, it cannot wait for return codes from remoce-sca- 
aons. Thus all returns concerning the object to be set can only come from the 
C^ FB) C ° nCr01 V * riabIeS ^ ° nly be l5caUn a PersonaJ Workstation .(a PW- 

2. Placing a local object (one found in the same station) on the import list is unneces-, - 
sary, so for local objects setval ignores that option. ' 

3. If a value is successfully set, its BAD and OOS status bits are automatically reset. 
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2.9 setvaljist - Set Value of an Object 



sesvaljistsezs the value of die specified object. This call is a variation of die omjserjalcall Ic 
differs only in the way the PSAP is specified. 

The ID of a currendy open (optimized or unopcimized) lisc and the index of a variable encry 
in die list are specified. The variable muse be connected. Ic is assumed chac die lisc variable and 
die cargec object reside in die same station. The^PSAP associated wich chac variable identifies 
the station co which die SETVAL message is sent, sewed _/zrris asynchronous; ic initiaces the 
SETVAL message and returns control co your process/task. 
Format: 

int setval_list (<narne>, <cbj_type>, <i:nport>, <value>, <s:=tus> ( <daca_ 
<open_ic>, <ov_incex>) 

char *nasie, *value; 

int o°j_type, import, cata_lan, open_id, ov_index; 

unsigned int *status; 



isn>. 



Where: 
♦name 
obj_type 
import 

*value 

♦status 



data_len 

open_id 
ov_index 
Return Codes: 
om_succsss 

H3ADTYPE. 



A poincer co die name of che object. 

The named objects cype; either VARIABLE or ALIAS. 

1 = Place die objects name on the import list. 

0 » Do noc place the objects- name on the import list. 

A pointer to the values location. Specify ics size in bytes using dataller, if 
it is a string or process variable, 

A pointer to the location where you have stored the objects daca cype 
(range 1-15)- 

An ALIAS object cype can only have STRING data cype. 
The shared VARIABLE object cype can have a data cype of CHARAC- 
TER, INTEGER, FLOAT, STRING, OM_BOOL (byce wich True/False 
values only), OMjlNGJNT (long inceger), OM_S_PKBOL (short 
packed boolean), or OMJLJPKBOL (long packed boolean). 
The Object: Manager docs not restrict process VAIUABLE daca types. All 
shared VARIABLE data types are supported plus CIO_SHORT (unsigned 
character). 

The length (in bytes) allocated for "value." This is needed for STRING 
data types and all process variables (0 deraulcs co size of float). 

ID of open variables lisc chac concains che variable to sec. 

Index of a variable encr/ within the lisc. 

The sec request has been initiated successfully. 
The specified data type is noc supported. 
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The specified daca cype does noc match che actual data cvpe (share- vari- 
ables only). See No ce 3. 

For ALIAS, che daca cype is noc STRING. 

For shared VARIABLE daca cype OM.BOOL, specified value is noc 1 
(True) or 0 (False). See Nocc 3. 
Object name coo Ions-. 

Process variable name with object cype noc equal co VARIABLE 

For STRING daca cype, specified string length coo long or < = 0. 

For STRING daca cype, specified string length longer chan actual strin* 
length. See Note 3. ~ ° 

Object cype DEVICE or PROCESS was specified. 
VARIABLE is secured. See Noce 3. 
Shared variable value record bad. See Nocc 3. 
Specified list noc open. 

Specified index greacer chan size of lisc. Specified index encry noc con- 
nected. 

Return Co de No ces: 

1. OM error codes are negative (refer co OMJECODE.H or Appendix B). 

2. Control and I/O (compound processor) recurns positive error codes (refer co che 
documenc System Messages). 

3. These error cases are returned only if che variable is local. 
Call Notes: 

1. Placing a local object (one found in che same scation) on che import list is unneces- 
sary, so for local objects setvaljist ignores chac option. 

• 2. If a value is successfully sec, its BAD andOOS status bits are automatically resec. 



S3ADMAME 



ESTRLZN 



ENOVALtTE 
ESECURE 
E3ADVREC 
ENOTOPENED 
~E3AD INDEX 
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2.1 0 st_omset_confirm - Set the Value and/or Status of 
an Object 

st_07nset_confirmsz& the value and/or the status of the specified object. This call is a func- 
tional extension of the Qm_set_confirm call. A status mask and a status data parameter allow 
the specification of object status bits to be set or reset. A status only parameter allows the writ- 
ing of status without an accompanying data value. This call works for shared variables, process 
- variables, and aliases. st_omset_confirm is synchronous; it initiates the SETVAL messase and 
waits for a response before returning control to your process/ task. 
Format: 

int st_omsat_conf ina(<naiae>, <ob j_type>, <import>, <value>, <stacus>, 
<data_len>, <?sap_ptr>, <st_dai:a>, <Sw_mask>, <sw_cnly>, <a??l_wor:<>} 



char 
int 

unsigned int 
PSAP_ADDR 



*name, * value, *appl_work; 
obj_type, import, dataller* ; 
*scatus, st_data, st_raask, sc_orily; 
*psap_ptr; 



Where: 
*name 
obj_ type 
import 

* value 

*status 



data_len 



*psap_ptr 



st^cata 



A pointer to the name of the object. 

The named objects type; either VARIABLE pr ALIAS. 

1 = Place che objects name on the import list. 

0 = Do not place the objects name on che import list. 

A pointer to the values location; Specify its size in bytes using cata_len if 
it is a string or process variable. 

A pointer to the location where you have stored the objects data type 
(range 1-15). 

An ALIAS object type can only have STRING data type. 
The shared VARIABLE object type can have a data type of CHARAC- 
TER, INTEGER, FLOAT, STRING, OMJOOL (byte wicir True/False 
values only), OM_LNG_INT (long integer), OM_S_PKBOL (short 
packed boolean), or OM_LJ?KBOL (long packed boolean). 
The Object Manager does not restrict process VARIABLE data types. All 
shared VARIABLE data types arc supported plus CIO_SHORT (unsigned 
character). 

The length (in bytes) allocated for "value". This is needed for STRING 
data types and all process variables (0 defaults to size of float). 

A pointer to che objects station PSAP address. A value of (PSAP_ADDR ") 
NULL indicates chat no PSAP has been provided (che call acts exactly che 
same as a set^conprm call) . 

Object status data bics. This word specifies the desired setting for the bits, 
specified in st_mask. Only bits defined in om_udef.h (BAD, OOS, and for 
process control variables only ACK) are allowed to be set/ reset. 
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sc_raasic 



st_only 



acpl_work 



Return Codes: 
0M — SUCCESS 
E3ADTYPE 



Object scacus mask bits. Bics set in this word specify die bits co set/reset 
according co cheir secting in die data word. If ic_mask is NUU the call 

T/n r ^V^V'r /CalL U crT k 15 NTJLL dlC ^ ^^'cally resets 
DAJJ and OOS tt a successful value set is performed. 

- If st_only is TRUE (non-zero), only a scam; sec is performed. The data 
value is noc ser. If st_only is TRUE and sc_mss!c is NULL the call is'a 

A pointer co a workstation ID scring. For applicacion programs, specify 
OiVLAPPLICATION (defined in om_udef.h). 



The sec request has been initiated successfully. 
The specified data type is not supported. 

The specified data type docs, not match the actual data type (shared vari- 
ables only). 

For ALIAS, the data type is noc STRING. 

For shared VARIABLE data type OM_BOOL, soecified value is not 1 
(irue) or 0 (False). 

Object name too long. 

Process variable name with object type noc equal co VARIABLE. 

For STRING daca cype, specified scring Iengch coo long or < = 0. 

For STRING daca cype, specified scring length longer chan actual serin* 
length. w ° 

Object type DEVICE or PROCESS was specified. 
Variable is secured. See Note 3. 
Shared variable value record bad. 
Object noc found. 

Object not found in specified station. Ascacion is specified by import able 
entry, PSAP parameter, or list ID and index parameters. 

Caller noc acrivated with IPC. 

System resource availability problem. 

IPC returned an unspecified error. 

Invalid bits set in wrice status mask. Valid bics are denned in om_udef.h. 
Workstation ID name invalid length (must be exacdy 13 characters). 
Return Code Notes: 

1. OM error codes are negacive (refer co OiVLECODE.H or Appendix B). 

2- Concrol and I/O (compound processor) returns posicive error codes (refer co che 
document Sysrem Messages) . 



E3ADNAHZ 



ESTRLEN 



ENOVALCJE 
ESECURE 
E3 AD VREC 
ENOCOiVFIRtf 
ENOTFOUND 

ENOT ACTIVE 
ENOSPACE 
EI PC RET 
E3ADMSX 
E3ADWXSTA 
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3. These error cases returned only if che variable is local. 
Call Notes: 

1. Placing a local object (one found in the same station) on the import list is unneces- 
sary, so for local objects sx^omsetjconfirm ignores that option. 

2- For process variables, BAD and OOS are always cleared before the masked status • 
write is performed. 
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i.\ 1 st__om_setval - Set the Val ue and/or Status of an 
Object 

st_om_setvd sets the value and/or.the status of the specified object. This call is a functional 
extension of the om^setval calL A status mask and a status data parameter allow the specifica- 
tion of object status bits to be set or reset- A status only parameter allows che writing of status 
without an accompanying data value. Thiicall works for shared variables, process JLiablcs, 
and aliases. st_om_setvalls asynchronous if the object is noc in the local station; it initiates the 
SETVAL message and returns control to your process/ask. * 
Format: 

inc st_om_setv<=il {<narae>, <cb j_type>", <import>, <valus>. <scaus>, <daca_lan>, 
<?sap_ptr>,<st_data>, <st_mask>, <sC_only>, <appl_work>j - 



char 
inc 

unsigned int. 
PSA?_ADDR 



•name, * value, •appl_wcrk; 
obj_type, import, data_lsn; 
•status, st_data, st_:nas!<, st_cnly; 
•psap_pcr; 



Where: 
*nane 
obj_type 
import 

•value 

•status 



dataller. 



r psap_pcr 



sc_data 



A pointer to the name of the object. 

The named objects type; either VARIABLE or ALIAS. 

1 = Place the objects name on the import list. 

0 s Do not place the objects name on the import list. 

Apo inter to the value's location. Specify its size in bytes using data lan. if 
it is a string or process variable. 

A pointer to the location where you have stored the objects data type 
(range 1-15). 

An ALIAS object type can only have STRING daca type. 

The shared VARIABLE object type can have a data type of CHARAC- 

TER, INTEGER, FLOAT, STRING, OMJOOL (byte with True/False 

values only), OM_LNG_INT (long inceger), OM_SJ?KBOL (short 

packed boolean), or OM_L_PKBOL (long packed boolean). 

The Object Manager does not restrict process VARIABLE data types. All 

shared VARIABLE data types are supported plus CIO_$HORT (unsigned 

character) . 

The lengch (in bytes) allocated for "value." This is needed for STRING 
data types and all process variables (0 defaults co size of float). 

A pointer to the objects station PSAP address. A value of (PSAP_ADDR ") 
NULL indicates that no PSAP has been provided (the call acts exactly the 
same as a setval call). 

Object status data bits. This word specifies the desired setting for the bits 
specified in st_mask Only bits defined in ornjidef.h (BAD, OOS, and for 
process control variables only ACK) are allowed to be set/ reset. 
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st_mask 



st:_only 



a-?pl_work 



Object stacus mask bics. Bits sec in this word specify che bics co set/resec 
according co cheir secting in chc daca word. If st_mask is NULL, che call 
performs like a serualcsll If st_mask is NULL, che call aucomacically resecs 
BAD and OOS if a successful value se: is performed. 

If st_on!y is TRUE (non-zero), only a status set is performed. The daca 
value is noc set. If sc_only is TRUE and sc_mask is NULL, the call is a 
NOP. 

A poincer to a workstation ID scring. For aoolication programs, specify 
OiVLAPPLICATION (defined in om_udef.h). 



Return Codes 

CM_SUCCESS 
E3ADTYPE 



The set request has been iniciaced successfully. 

The specified daca cype is not supported. 

The specified data type does noc macch che actual daca cype (shared vari- 
ables only). See Noce 3. 

For ALIAS, the daca cype is noc STRING. 

For shared VARIABLE daca type OiM_BOOL, specified value is noc 1 
(True) or 0 (False). See Noce 3. " 

ebadname Object name coo long. 

Process variable name with object type not ecjual to VARIABLE. 

EST RL EN For STRING data cype, specified string length coo long or < = 0. 

For STRING daca cype, specified string length longer chan actual string 
length. See Note 3- 

enovalue Object cype DEVICE or PROCESS was specified. 

ESECURE VARIABLE is secured. 

E3ADVREC Shared variable value record bad. See Note 3. 

E3ADMSK Invalid bits set in wricc stacus mask Valid bics are defined in om_udef.h. 

EBADWXSTA Workstation ID name invalid length (must be exacdy 13 characters). 

Return Code Notes: 

1. OM error codes are negative (refer to OM_ECODE.H or Appendix B). 

2. Control and I/O (compound processor) returns positive error codes (refer co che 
documcne System Messages). 

3. These error cases are returned only if che variable is local. 

4. If a value is successfully set, its BAD and OOS stacus bics are automatically reset. 
Call Notes: 

1. Since chis call is asynchronous, it cannoc wait for return codes from remote sca- 
■ tions. Thus all returns concerning the object to be set can only come from the 

local station. Concrol variables can only be local in a Personal Workscacion (a PW- 

CorPW-FB). 
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2. Placing a local object (one found in the same stacion) on the import list is unneces- 
sary, so for local objects st_om_setval ignores chat option. 

3. For process control variables, BAD and OOS are always cleared before the masked 
status write is performed. 
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I 2.12 st_setcnf - Set the Value and/or Status of an 
Object 

j sumtfm che value and/or che status of the specified object. This call Is a functional exten- 
sion of the set_confirm call. A status mask and a status data parameter allow the specification 
of object status bits to be set or resec. A status only parameter allows the writing of scatus with- 
out am accompanying data value. This call works for shared variables, process°variabies, and 

I aliases, s^serenfts synchronous; it initiates the SETVAL message and waits for a response 

before returning control to your process/task. 
Format: 

I mfc «t_3«fcesff (<«»•>, <obj_cy?e>, <import>, <value>, <3ta=us>, <data_l*">, 

J <s:: - ca{::a> '<sli_rnask:> / <st:_only> l <appl_wor!<» 

1 char *narae, 'value, *appl_wor!<; 

' int coj_ty?e, import, data.Ian; 

I unsigned int * status, st_data, stjnasfc, sr_cr.ly; 

Where: 

* na:ne A pointer to the name of the object, 

ob j_typ e The named objects type; either VARIABLE or ALIAS. ' 

import 1 = Place the objects name on the import list. 



•value 



'status 



0 = Do not place the objects name on the import lisc. . - 

A pointer to the values location. Specify its size in byces ustns dataller, if 
it is a string or process variable. 

A pointer to the locadon where you have stored the objects data cype 
l (range 1-15). 

An ALIAS object cype can only have STRING data type. 
1 The shared VARIABLE object type can have a data cype of CHARAC- 

TER, INTEGER, ELOAT, STRING, OM_BOOL (byte with True/False 
values only), OM_LNG_INT (long integer), OM_S_PKBOL (short 
I packed -boolean), or OM_LJ?KBOL (long packed boolean). 

* The Object Manager does no c restrict process VARIABLE daca types. All 
. shared VARIABLE daca cypes are supported 'plus CIO_SHORT (unsigned 
character). 

I caea.len The length (in bytes) allocaced for "value". This is needed for STRING 

data types and all process variables (0 defaults co size of float). 
st_data Object status daca bits. This word specifies che desired sectins; for che bits 

specified in st_mask. Only bics defined in om_udef.h (BAD, OOS, and for 
process control variables only ACK) are allowed co be sec/ resec. 

st_mask Object status mask bics. Bics sec in chis word specify che bics co set/ resec 

according co cheir sectirtg in che daca word. If st_mask is NULL, che call 
performs like a stmd call. If sc_mask is NULL, che call aucomacically resecs 
BAD and OOS if a successful value sec is performed. 
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s"_only 

a??I_work 

Return Codes: 

CM_SUCCES3 

E3ADTYPE 



If st_only. is TRUE (non-zero), only a status se: is performed. The data 
value is noc set. If st.only is TRUE and sc_mas!c is NULL, che call is a* 
NOP. 

A pointer co a workstation ID string. For aoplication programs, spe-ify 
OM_APPLICATTON (defined in om.udef.h). 

The set request has been initiated successfully. 
The specified data type is not supported. 

The specified data type does not match the actual daca cype (shared vari- 
ables only). 

For ALIAS, the data cype is not STRING. ~ 

For shared VARIABLE data type OM_BOOL, specified value is noc 1 
(True) or 0 (False). 

Object name too long. 

Process variable name with object cype not equal to VARIABLE. 

For STRING data type, specified string length coo long or < = 0. 

For STRING data cype, specified string length longer than actual string 
length. 

Object cype DEVICE or PROCESS was specified. 
Variable is secured. See Note 3. 
Shared variable value record bad. 
Object not found. 

Object not found in specified station. A station is specified by import able 
entry, PSAP parameter, or list ID and index parameters. ENOTFOUND 
occurs when che object is on che import list, but the stadon listed as its 
home cannot find it. This means that the object' has probably been moved 
to another stadon. 

Caller noc activated with IPC. 

System resource availability problem. 

IPC returned an unspecified error. 

Invalid bits set in write status mask. Valid bits are defined in 
OM_UDEF.H. 

Workstation ID name invalid length (must be exactly 13 characters). 
Return Code Noces: 

1. OM error codes are negative (refer co OMJECODE.H or Appendix B). 

2- Control and I/O (compound processor) returns posicivc error codes (refer co che 
documcne System Messages). 

3. These error coses are returned only if che variable is local. 



^EADNAME 



ESTRLEN 



ENO VALUE 
ESZCuRE 
E3ADVREC 
ENO CONFIRM 
ENOTFOUND 



ENOT ACTIVE 
ENOSPACE 
EI?CRET 
E3A0MSX 



ADWXSTA 
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Call Notes: 

1. Placing a local object (one found in die same station) on che import list is unneces- 
sary, so for local objects jr_^faz/ignorcs that option. 

2. For process control variables, BAD and OOS are always cleared before che masked 
status write is performed. 
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2.1 3 st_setl'ist_confirm - Set the Value and/or Status of 
an Object 

st r sedist_confirm sets chc value and/or che scacus-of chc specified object This call is a ftinc 
nond extension of che ^/1/irrcaJL A status ma,k and a status data parameter allow the 
speahcaaon of object status bits to be set or reset. A status only parameter allows the writin* 
at status without am accompanying data value. This call works for shared variables, process * 
variables, and aliases. sy*lm_cmfirm is synchronous; it initiates the SETVAL message and 
waits tor a response before returning control co your process/ cask. 
Format: 

^VV setlisfc - confira ^ 

aata_len>, <open_id>, <ov_index>, <st_cata>, <sc_mas!<>, <st.only> f <a P? Lwork» 
char *naaie, *value, ~appl_wcr!<; 

int obj^type, imporc, cata_len, open_id, *ov_index; 

unsigned int -.status, st_data, sr.rnask, st_only ; 



Where: 
*name 

import 
*value 
♦status 



data_len 

open_id 

ov_index 

st_data 

stomas !< 



A p.o inter to the name o f the obj ect. 

The named objects cype; either. VARIABLE or ALIAS. 

1 = Place the objects name on che import list. 

0 = Do not place the objects name on the import list. 

A pointer to che values location. Specify its size in bytes using data_len if 
it is a string or process variable. 

A pointer to the location where you have stored the objects data type 
(range 1-15). 

An ALIAS object cype can only have STRING data type. 
The shared VARIABLE object type can have a data type of CHARAC- 
. TER, INTEGER, FLOAT, STRING, OMJOOL (byte with True/False 
values only), OMJLNGJNT (long integer), OM_S_PKBOL (short 
packed boolean), or OM_L_PKBOL (long packed boolean). 
The Object Manager does, not restrict process VARIABLE data cypes. All 
shared VARIABLE daca cypes arc supported plus CIO_SHORT (unsigned 
character). ° 

The length (in bytes) allocaced for "value". This is needed for STRING 
daca cypes and all process variables (0 defaults co size of floac). 

ID of open variables lisc chac concains che variable co sec. 

Index of a variable encry within chc list. 

Object status data bits. This word specifies che desired seccing for che bics 
specified in st_mask. Only bics defined in om_udef.h (BAD, OOS, and for 
process concrol variables only ACK) are allowed co be sec/resec. 

Object scacus mask bics. Bics sec in chis word specify che bics co sec/resec 
according co cheir seccing in che daca word. If sc_mask is NULL, che call 
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st_oniy 



Return Codes: 

OM.SUCCSSS 
E3ADTYP2 



performs like a savalall If st.mask is NULL, che call automatically resets 
BAD and OOS if a successful value sec is performed. 

If st_only is TRUE (non-zero), only a scacus sec is performed. The daca 
value is noc set. If st_only is TRUE and st_mask is NULL, die call is - 
NOP. 

A pointer .to a worksrarion ID string. For aoplicacion programs, spc^'fir 
OM_APPUCATION (defined in om_udef.h). ~ 



The sec request has been initiated successfully. 
The specified data type is noc supported. 

The specified daca cype does not match the actual data type (shared vari- 
ables only). 

For ALIAS, the data cype is not STRING. 

For shared* VARIAB L£ data cype OM.BOOL, specified value is not 1 
(True) or 0 (False). 

Object name too long. 

Process variable name with object type not equal co VARIABLE. 

For STRING daca type, specified string length coo long or < « 0. 

For STRING data cype, specified string length longer than actual string 
length. 

Object cype DEVICE or PROCESS was specified. 
Variable is secured. 
Shared variable value record bad. 
Object not found. 

Object not found in specified station. A station is specified by import table 
entry, PSAP parameter, or list ID and index parameters. 

Caller not activated with IPC. 

System resource availability problem. 

IPC returned an unspecified error. 

Specified list noc open. 

Specified index grcacer chan size of lisc. Specified index entry not con- 
nected. 

Invalid bits set in wrice stacus mask. Valid bits are denned in om_udef.h. 
Worbcacion ID name invalid lengch (must be exactly 13 characters). 
Re turn Co de No tes: 

1. OM error codes are negative (refer co OiVLECODE.H or Appendix B). 



E3ADNAMS' 



ESTRLEN 



ENOVALUE 

ESECtfRE 

E3ADVREC 

ENCCONFISM 

ENOTFOUND 

ENOTACTIVE 
BIOS PACE 
EIPCRET 

ENOTOPENED 

t 

E3 AD INDEX 

E3ADMSK 
E3ADWKSTA 
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2. Control and I/O (compound processor) returns positive error codes (refer to the 
document System Messages) . 

3. If a value is successfully set, its BAD and OOS status bits are automatically reset. 
Call Notes: 

1. Placing a local object (one found in the same station) on the import list is unneces- 
sary, so for local objects st_sedisc_confirm ignores that op don. 

2. For process control variables. BAD and OOS are always cleared before the masked 
status write is performed. 
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2.14 st_setjist - Set the Value and/or Status of an 
Object 

st-S&Jzstscts the value and/or die status of die specified object. This call is a functional exten- 
sion of the sewdjist call. A status mask and a status data parameter allow the specification of 
object status bits to be set or reset. A status only parameter allows the writing of status without 
am accompanying data value. This call works for shared variables, process variables, and 
aliases. st_ser_list is asynchronous if the object is not in the local station; it initiates the SET- 
VAL message and returns control to your process/ task. 
Format: 

int st_sat_list: (<name>, <chj_type>, <imporw>, <value>, <scatus>, <data_ler.>, 
<epen_id>, <ov_index>, <sc_daca>, <s.i:_maslc>, <st_cnly>, <a?pl_vcrk>) 

cha.r *naxne, * value +appl_work; 

int . obj_ty?e, imporc, cata_len, open_id,ov_ir.cex; 

unsigned int *status, st_data, st_raask, st_only; ■ 



Where: 
*name 
osj—type 
import 

*value 

*status 



data_len 

open_id 

ov_inde;< 

st_cata 

stomas k 



A pointer to the name of the object. 

The named objects type; either VARIABLE or ALIAS. 

1 = Place the objects name on the import list. 

0 = Do fiot place the objects name on the import list. 

A pointer to the values location. Specify its size in bytes using dataller, if 
it is a string or process variable. 

~ A pointer to the location where you have stored the objects data type 
(range 1-15). 

An ALIAS object type can only have STRING data type. 
The shared VARIABLE object type can have a data type of CHARAC- 
TER, INTEGER, FLOAT, STRING, OMJOOL (byte with True/False 
values only), OM_LNG_INT (long integer), OM_S_PKBOL (short 
packed boolean), or OtM_L_PKBOL (long packed boolean). 
The Object Manager docs not restrict process VARIABLE data types. All 
shared VARIABLE data types are supported plus CIO_SHORT (unsigned 
character). 

The length (in bytes) allocated for "value." This is needed for STRING 
data types and all process variables (0 defaults to size of float). 

ID of open variables list that contains the variable to set. 

Index of a variable entry within the list. 

Object status data bits. This word specifies che desired setting for the bits 
specified in st_mask. Only bits defined in om_udef.h (BAD, OOS, and for 
process control variables only ACK) are allowed to be set/ reset. 

Object status mask bits. Bits set in chis word specify che bits to sec/rese: 
according to their secting in che daca word. If sc_mask is NULL, che call 
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only 

appl_wor!< 

Recurn Codes: 
OM_SUCCZSS 
HSADTYPS. 



performs like a *n«/caIL If sc.mask is NULL, che call aucomacicaily resets 
BAD and OOS if a successful value sec is performed. 

If sc_only is TRUE (non-zero), only a scacus se: is performed. The daca 
value is noc sec. If sc_only is TRUE and sc_mask is* NULL, che call is a 

A poincer co a workscacion ID string. For application programs soe-ifV 
OM_APPLICATION (defined in om.udef.h). F ^ 



The sec request has been initiated successfully. 
The specified daca type is noc supponed. 

The'specified daca type does noc macch che accual daca cype (shared vari- 
ables o nly) . See No ce 3 . 

For ALIAS, che data cype is noc STRING. 

Foe shared VARIABLE daca cype OM.BOOL, soecified value is noc 1 
(True) or 0 (False). Sec Noce 3. 

Objecc name coo long. 

Process variable name wich objecc cype noc equal co VARIABLE. 

For STRING daca cype, specified scring length coo lono"or < = 0. 

For STRING daca cype, specified scring length longer than accual serine 
length. See Note 3- ° 

Object type DEVICE or PROCESS was specified. 

VARIABLE is secured. See Note 3. 

Shared variable value record bad. See Noce 3. 

Specified list not open. 

Specified index greater than size of list. Specified index entry not con- 
nected. " 

Invalid bits set in write status mask. Valid bits are defined in om_udef.h. 
Workscacion ID name invalid length (muse be exactly 13 characters). 
Recurn CodeNoces: 

1. OM error codes arc negacive (refer to OiVLECODE.H or Appendix B). 

2. Control and I/O (compound processor) returns positive error codes (refer to the 
document System Messages). 

3. i hese error cases are returned only if che variable is local. 
Call Notes: 

1. Placing a local objecc (one found in che same station) on the import list is unneces- 
sary, so for local objects st_se:_l:st ignores that option. 



£3 AD MAKE 



ZSTRLZN 



ENOVALUE 
ESECORE 
H3ADVRZC 
KNOTOPEMZD 
ESAD INDEX 

E3ADMSX 
E3ADWXSTA 
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2- For process concrol variables, BAD and OOS arc always cleared before chc masked 
scams write is performed. 
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2.15 st_setva! - Set the Va! ue and/or Status of an 
Object 

sU^alsczs che value and/or che scacus of chc specified object. This call is a functional exten- 
sion of the setval call. A scacus mask and a status data parameter allow che specification of 
object stacus bits to be sec or reset. A scacus.only parameter allows the writing of status with- 
out an accompanying daca value. This call works for shared variables, process** variables, and 
aliases. st_setval\s asynchronous if the object is not in the local station! it initiates the ' 
SETVAL message and returns control to your process/cask. 
Format: _ 

lnC * c - MCv *l (<name>, <cb j_typa>, <import>, <value>, <scatus>, <cata 1 an> 
<sc - da -ta>, <sc_mask>, <sc_only>, <appl_work>) 

char •name, 'value, *appl_worfc; 

lnt ob j_type, import, dataller.; 

unsigned int -status, st^data, st_mask, st_only; 



Where: 
"name 

ir.porc 
* value 
^status 



data_len 
sc_daca 

sc_mask 



A pointer to the name of the object. 

The named objects type; either VARIABLE or ALLVS. 

1 = Place the objects name on the import list. 

0 = Do not place the objects name on the import list. 

A pointer to the values location. Specify its size in bytes usins cata_len if 
it is a string or process variable. 

A pointer to the location where you have stored the objects data type 
(range 1-15). 

An ALIAS object type can only have STRING data type. 
The shared VARIABLE obi cct type can have a- data type of CHARAC- 
TER, INTEGER. FLOAT. STRING, OM_BOOL (byte with True/False 
values only), OM_LNG_INT (long integer), OM_S_PKBOL (short 
packed boolean), or OM_L_PKBOL (long packed boolean). 
The Object Manager does not restrict process VARIABLE data types. All 
shared VARIABLE data types are supported plus CIO_SHORT (unsigned 
character). " 

The length (in bytes) allocated for "value." This is needed for STRING 
data types and all process variables (0 defaults to size of float). 

Object status daca bics. This word specifies che desired setting for the bits 
specified in sc_mask. Only bits defined in om_udef.h (BAD, OOS, and for 
process control variables only ACK) are allowed to be sec/ reset. 

Object status mask bits. Bits sec in chis worked specify che bics to sec/ reset 
according co chcir setting in chc daca word. If si_mask is NULL, che call 
performs like a serial czll If st_mask is NULL, che call aucomacically resets 
BAD and OOS if a successful value sec is performed. 
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st_on!y 

appI_work 

Renim Codes: 
OM_SUCCESS 
E3 AD TYPE 



If st_on!y is TRUE (non-zero), only a status sec is performed. The daca 
value is noc set. If st_only is TRUE and sc_mask is NULL, die call is a 
NOR 

A pointer co a workstation ID string. For application programs, specify 
OM.APPLICATION (defined in om_uder.h). 



The set request has been initiated successfully. 
The specified data cype is not supported. 

The specified data type does noc match the actual data type (shared vari- 
ables only). See Note 3. 

For ALIAS, the data cype is not STRING. 

For shared VARIABLE data type OtM_BOOL, specified value is not 1 
(True) or 0 (False). See Note 3. 



E3ADNAME 



Object name too long. 

Process variable name with object type not equal to VARIABLE. 

ESTRLEN For STRING data cype, specified string length too long or < = 0. 

, For STRING data type, specified string length longer than actual string 
length. See Note 3. 

ENOValue Object type DEVICE or PROCESS was specified. 

esecure VARIABLE is secured. See Note 3. 

E3ADVREC Shared variable value record bad. See Note 3. 

E3ADMSX Invalid bits set in write status mask. Valid bits are defined in om_udef.h. 

E3ADWKSTA Workstation ID name invalid length (must be exacdy 13 characters). 

Return Code Notes: . . 

L OM error codes are negative (refer co OM_ECODE.H or Appendix B). 

2. Compound I/O (compound processor) returns positive error codes (refer to the 
document System Messages). ~ * 

3. These error cases arc returned only if the variable is local. 
Call Notes: 

1. Since this call is asynchronous, it cannot wait for return codes from remote sea- - 
tions. Thus all returns concerning the object to be set can only come from che 
local station. Control variables can only be local in a Personal Workstation (a PC 
PW-CorPW-FB). 

2. Placing a local object (one found in the same stacion) on the import list is unneces- 
sary, so for local objects stjtetval ignores chat option. 

3. For process control variables, BAD and OOS are always cleared before che masked 
status write is performed. 



3. C Ca//5 fo Access/Update Sets of 
Variables 



These calls allow your cask co establish Uses of process variables (using omopen) wich values 
indicating how much change has co cake place in che variable's value before your cask is nori- 
fied (by dqchange). 

Copies.of che values and scacus of che variables in an opened lisc are maincained locally so chac 
the response on reads is immcdiace and requires no addicional network crafHc. These calls are 
designed for casks needing ongoing access co many proce ss var iables. 

A cask can read from or wrice co variables on a list returned by omopen unril you issue an 
omciose. Ac that rime (for optimized lists) che Object Manager returns a table of addresses 
where it found che variables. 

Subsequent omopem can use the same table of addresses, thus saving processing time. 

The OM C calls to access/update sets of variables are listed in this Section in alphabetical 
order and summarized in Table 3-1. 



Table 3-1. C Calls to Access/Update Sets of Variables 



Paragraph 
No. 


Call 


Function 


3.1 


dqchange 


Check for object value changes 


3.2 


dqlisc 


Dequeue open variables lisc 


3.3 _J 


omciose 


Close che specified variable lisc 


3.4 


omopen 


Ooen a sec of variables 


3.5 


omread 


Read values from opened lisc 


3.6 


omwrice 


Wrice values co opened lisc 


3.7 


omwrscac 


Wrice values and/or scacus co opened lisc 
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3.1 dqchange - Check for Object Value Changes 
3.1.1 dqchange call 

This call dequeues the notification or change in a variable lis: which die specified process has 
opened (with omopen). The list is enqueued when a change-driven evenc occurs co a variable 
wichin che list, and the list is noc already in che change queue. The updated informacion is 
also copied inco che list. In order co register as a change, che change has co be greacer chan or 
equal co the delta_value (in che omapen call) or che status has co change. To be nodfied, set che 
NOTIFY option in che list ac omapen rime. If che NOTIFY flag is sec, che header node for che 
open variables list is linked co che end of a change notification queue, and che change notifica- 
tion message is posced co the mailbox for chac queue. Change queues are created and managed 
by che Object Manager on a per process basis. Change notification for a given lisc is placed on 
che queue for che process chac opened che lisc. The dqchangd) caller specifies a process ID, and 
therefore identifies a particular change queue. 
Format: - 

int dqchange (<pid> / <susper.c>, <cper._id>, <size_lisc> , <value_list>, 
<ret_size>) " ^ ~ 

int pid, suspend, size_list ; 

infc *open_id, *rec_size; 

struct ..value *value_list; 



Where: 
pid 

suspend 
OUT" *cperi_id 
size_list 
*value_list 

*ret_size 



The process id number of che process chac opened che target lisc. 

1 * Suspend execution until a change comes in. 

0 = Do noc suspend; if no changes, return code = EQJEMPTY. 

A poincer co che inceger location chac will receive che opened which cells 
you che first variable lisc chat was found co have changes. 

The number of elements in the value structures array that you have created 
to receive the changed values. 

A pointer to the caller-supplied array of structures. Each new/ changed 
value is returned in one of the array elemenc scructures. The array of 
"value" structures is described below. 

A poincer co che location where the Object Manager returns che number of 
changed variables returned. 



struct value { 



ur.icr. 



ir.cax; 

status ; 

var_val ( 
char 
ir.t 
float 



Letts: 
wprd; 
fee in: 
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} uval; 
} values [ ] ; 

index The index value inco che variable Use corresoondino- co che 

variable chac changed. 



status 



The daca cype and status of che variable chac changed: 



Return Codes: 

OM_SUCCESS 
ESECtfRE 



0 = This value noe read ye:, check for error 

Daca cype - Low byte, bits 0 co 4 

1 = CHARACTER 5 = BOOL 

2 = INTEGER 6 = OM_LNG_INT or POINTER 

3 = FLOAT or REAL 9 = OlVLPACKED_BOOL 

4 = STRING 10 = OiV(_LONG J>ACKED_BOOL 

Error stacus — Low byte, bics 5 co 7 

0 a No response 4 = Bad daca cype (scring) 

1 = Being scanned or unconnecrable compound 

2 = Disconnected 5-6 = (noc used) 

3 = Deleted, 7 = noc sen: (error returned) 

uval The actual value 0 f che variab le. 

rat_size Number of clemencs returned. 

Changed variables have been successfully returned. 



The omopen specified write zeeess and actempced co connect co a variable 
which had been previously secured for write access. None of the variables 
arc connected. The caller should perform an omclose co close che lisc* 

The specified process id did noc perform any omopens which resulced in 
leaving a list opened, or che omopen did noc specify any variables for noti- 
fication access. 

The omopen could noc escablish an IPC conneccion because no connec- 
tions were left. You should close che list using che omclose. 

The scructure tt var" array, supplied by che user, is coo small co hold all che 
changes chac che Object Manager has in ics queue. 

You did noc specify che suspend opcion and che queue does noc concain che 
specified list. 

Connection was busy on ac least one station. The ochers are opened. There 
is no auto-reconnect. 

Call Notes: 

1- Each variable list is identified by the openjd returned when the list was opened. 



ENOTOPENED 



ECONNBAD 



EQ MOT EMPTY 



EQEMPTY 



0M_EC3SY 



2. You can specify any cask (process Jd) that ha^ open lists. If more than one list has 
changes, dqchange rerurns chose in die first lisc, chen removes that Iisc from ics 
queue. Use anocher call co get che changes in che nexr list. & 



3. There is a macro, v_variist(s), chac scacicaily or dynamically allocates che value 
scrucmre for you. This macro is defined in che om_user.h include file: 

Scefine v_varlisc(s) valloc (sizaof( struct value- '3) 
1 he following is an example of how this macro could be used: 

siza^list: = 10; 

value_list = v_varlisc (10) ; 

if (value_list == (struct value *) MULL) 

{ 



} 



The firsr line sees che size_list calling argumenc. The second line dynamically allo- 
cates a 10-element array of "value" structures. 

If you use this macro, be sure to free che memory when che structure is no longer 
needed. It is alsq^advisable to check chac che macro did noc return a NULL pointer 
indicating insufficient available memory. 

4. A process id number is maintained by che operating system for every task. A task 
can retrieve its own process id number using che getpid command. For more infor- 
mation on gecpid(2) refer to the UNIX Programmer's Reference Manual You can 

issue a dqchange for che variable list of some other cask, but since you can only use f 7: ■ "* 

getpid for your own cask number, che ocher task has to have sent you its process id. ~' 

5. Be careful of specifying thac chis call suspend. If an omopen failed, and you 
dqchange with che suspend option, it suspends forever. Check your omopens to 
make sure they were successful. 

3.1.2 Change Queues 

The Objecc Manager has the ability to search a queue, and to dequeue an element regardless 
.ofits position wichin che queue. " - 

The Process/Queue Table is a high level data scrucrure used co manage change 'queues. This is 
an array of change queue descripcors dynamically allocated by code, and pointed to by process 
queue cables. 

A change queue descriptor contains che ID of the process or task for which the queue has been 
allocated. There is no more chan one queue per ID, so the ID is passed co dqchange^oz dqlistft 
to identify a particular change queue. 

A process/task with ac lease one currendy open lisc containing change driven variables has a 
change queue allocated for it. The queue descriptor contains the current number of change 
driven liscs opened by che process. The queue descriptor is free and may be (re)allocatcd when 
che count is zero. 
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The change queue is a singly linked FIFO queue of open variable lisc headers. Head and rail 
pointers are kepc in ch c queue descriptor. The headier member points co the first list header 
in ^e queue, and th c cail_ctr member points to the NULL pointer that terminates the 
linked queue. If the queue is empty, the h S ac_ptr contains NULL, and the tan c — points 
to the hsad_=cr. 

A list header is added to thc tail of thc queue by storing a pointer co che list header at the loca- 
tion indicated by tail.jp tr. Then tailjtr is changed to point into thc list header, to che 
NULL pointer terminating che queue. 

When dqchang^) removes a lisc header from chc queue, it is the header to which haad_otr 
points. When dqlist removes a header, it is a header that may have been found anywhere 
within che queue. Thc header is removed from the queue and poincers are updated. If remov- 
ing thc header leaves che queue empcy, thc tail_ocr must be updated to point to head_ptr. 
The UNLX semaphore in a change queue descriptor is for use with the system calls. When a 
queue is empty and the dqchangeQ caller wishes to suspend until the next change notification, 
it is accomplished using a system call that specifies "chc semaphore associaced in the queue 
descriptor. When a change occurs, notification is accomplished using a matching call. 
Thc following diagram shows the change queue hierarchy. There are three change queue 
descriptors in use. This means that there are three processes with open lists of change driven 
variables. One of the queues is empty. For two of thc processes, changes co lists have occurred" 
but have not yet been seen by the application. 
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prac_que_tbl 

change queue descriptors 



PID 


P!D 




PID 






cnt >=1 


cnt > 0 


cnt > 0 


cnt >=2 


cnt = 0 




head pt 


head pt 




head pt 






tail pt 


tail pt 




tail pt 






semiphr 


semiphr 




semiphr 







header_node 



vars list 



header_node 



vars list 



cnt = 0 




header node 



vars list 
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3.2 dqlist- Dequeue Open Variables List 

i his call dequeues che notification of change wichin che specified open variables list. The list 
is enqueued when a change driven event occurs to a variable within the li sc , and the list is not 
already in the change queue. The updated information is copied into the lisc. 
Like dqchange, dqlist specifics a process ID, and therefore identifies a particular change queue. 
The list must have been opened by the specified process. No change notifications can be 
found otherwise. When this call is made, the Object Manager checks the change queue associ- 
ated with the specified process ID for the change notification for the specified list. If the list is 
not in the change queue than the call returns 5QEZ*?ty (whether or not the queue is actually 
empty). Once the change notification for the list is found in the change queue, it is removed 
from the queue. The value list information is returned to the caller, and the dqtatQ call 
returns om_Su'cczss. 

Format: 

.ine dqlist (<?id>,<suspend>,<open.J.d>,<size_iist>,<value_list> / <ree siza>) 
lnc pid, suspend, size_list; 

lnc *open_id, *ret_sizI7 

struct value *vaiue_list; 



"Where: 
pid 

suspend 

size_list 

*opea_id 

*value_list 
*ret_si2e 



The process id number of che process chat opened che career lisc, 
0 - Must be a. zero. Cc vvoT < T^± f Cz/C>% 
The number of elements in che values array. 

Inceger ID of che cargec list. The ID is obcained from che previous ornopen 
call. The list must currendy be open. 

A pointer to che caller-supplied array of structures. Each new/changed 
value is returned in one of che array elemenc scructures. The array of 
"value" structures is described below. 

A poincer co an inceger which receives che number of array elemencs con-r 
caining returned variables. . 

struct value { 



in: 
int 
union 



index; 

status; 

var_val { 
char 
int 
float 



letter; 
wcrd; 
f point ; 



} uvai; 
} values ( ] ; 



index The index value inco che variable lisc corresponding co che 

variable chac changed. 
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status 



1 he data type and status of the variable chat changed: 



Return Codes: 

CM_SUCCZSS 

ESECUR2 

EMOTOPHNZD 

ECONNBAD 
EQN0T2MPTY 



0 = This value not read yet, check for error 

Data type - Low byte, bits 0 to 4 

1 = CHARACTER 5 = BOOL * 

2 = INTEGER 6 = OM.LNG JNT or POINTER 

3 = FLOAT or REAL 9 = OM.PACKED JOOL 

4 = STRING 10 = OM_LONGJ?ACKED_BOOL 

Error Status —Low byte, bits 5 to 7 

0 = No response 4 = Bad data cype (string) 

1 = Being scanned or unconneccable compound 

2 » Disconnected 5-6 ■ (not used) 

3 = Deleted 7 = not sent (error returned 

uval The actual value of the variable. 

r^t_size Number of elements returned. 

Changed variables, have been successfully returned. 

The omopen specified write access and attempted to connect to a variable 
which had been previously secured for write access. None of the variables 
are connected. The caller should perform an omclose to close the list. 

The specified process id did not perform any omopens which resulted in 
leaving a list opened, or the omopen did not specify any variables for nori- 
ficacion access. 

The omopen could not establish an IPC connection because no connections 
were left. You should close the list using the omclose. 



EQEMPTY 



The structure "var" array, supplied by the user, is too small to hold all the 
changes that the Object Manager has in its queue. 

You did not specify the suspend option and the queue does not contain 
the specified list. 
Call Notes: 

1. Each variable list is identified by the openjd returned when the list was opened. 

2. There is a macro, v_varlist(s), that statically or dynamically allocates the value 
structure for you. This macro is defined in the om_user.h include file: 

^define v_varlist(s) valloc (sisaoc (struct value) 's! 
The following is an example of how this macro could be used: 
siza_list = 10; 
value_list = v_varlis t ( 10 ) ; 
if (value_list == (struct value *) NULL) 
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} 



The first line sees eke sizejisc calling argument. The second line dynamically allo- 
cates a 10-elcment array of "value" structures. 

If you use this macro, be sure to free the memory when the structure is no longer 
needed. It is also advisable to check that the macro did not return a NULL pointer 
indicating insufficient available memory. 

3. A process id number is maintained by the operating system for every task. A task 
can retrieve its own process id number using the getpid command. For more infor- 
mation on getpid(2) refer to the UNIX Programmer Reference ManuaL You can 
issue a dqlist for the variable list of some other cask, but since you can only use »et- 
pid for yout-own task number, the other task has co have sent you its process id. 
^XBe^careful of specifying that this call suspend. If an omopen railed, and you dqlist 
JVKh che suspend option = 1, it suspends forever. Check your omopens to make 
^ure they wcre successful. 
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3.3 omclose - Close the Specified Variable List 

This call closes a Use of local or remote variables by releasing che connection established wich 
die omopen call. It also supplies ail of the header information, variable list, and address table 
to speed up future omopen calls to .the same list. 

omclose is asynchronous; it initiates the request then immediately returns control to your task. 
Format: 

int omclose (<open_ic>, <headar>, <var_iist>, <addr_tbl>} 
in >£ c?en_id; 
s cruet om_header_ncde 'header; 
struct open_var *var_list; 
struct net_addr -*addrj:bl; 



Where: 




open_id 


The id number returned from the omopen call. 


* header 


A pointer to the cra_header_node structure.' 


*var_list 


A pointer to the value structures array. 


-adcr_tbl 


A pointer to the address table for the list. 


Return Codes: 




OM_S'JCCHSS 


The request has been initiated. 


ENOTO?END 


There is no open list corresponding to this open_id. 


ENOTACTIVE 


Not registered with IPC for connectionless service. 


EI?CR£T 


You have an unspecified IPC error other than HNOTACTIVZ. 


Call Notes: 





1. The header node and. variable list (and address table, if opumized) are returned so 
you can specify them the next dme you open this list. When the Object Manager 
is passed an optimized list with a network address table, it can open the list much 
more quickly. 

2. Do not modify the optimized list structures if the list is to be opened again at a 
later time. 

3. It is imperative that the lists be closed before any exit from the program. 
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This call opens a list of up co 255 local or remote variables, omopen operates on a list of local 
and/or remote variables, creating a set of connections to the variables. These connections 
must be made before an/ data access can be done on the set of variables using the list. There- 
fore, you muse use this call before using an/ of the other list access calls. There are both opti- 
mized and unoptimized versions of omopen. This call is asynchronous for local variables; it 
initiates the request and then immediately returns control to your task. This call is synchro- 
nous for remote variables; you must wait until the transmission of remote open messages is 
complete. 

Format: 

int omopen (<om_descriptor>, <open_id> J 

struct om_header_node »cra_descriptor ; 

*cpen_ic; 



int 
Where: 

*om_descriptor 

*open_id 

Rerurn Codes: 
OM_SUCCESS 
E3ADRSZ 

ENO ACTIVE 

ENOTFOUND 

ENOQCJE 

EOMOSIZE 

ESZCURZ 

ENO SPACE 
EOPEHED 
E3ADLIST 
EC0NN3AD 



A pointer to the header_noce data structure, described in paragraph 3.4.1, 
Optimized and Unoptimized omopen calls. 

A pointer to the location where the Object Manager returns the list num- 
ber. 



The list has been opened- 

For an optimized list, being opened the first time, the current size of the 
Network Address Table is not zero. The list is not opened. 

Call not registered with IPC for connectionless communications. List is 
opened, but remote variables not being scanned. 

One or more variables can't be found; the rest are being scanned/unopri- 
mized version only) 

The list specified change notification and there are no change queues avail- 
able. The list is not opened. 

The size of the open variable list exceeds the maximum. The list is not 
opened, 

A connection was attempted to a variable which has previously been con- 
nected for write zeezss. If this error is returned, none of the variables in the 
list arc connected. The list is opened but not available for write access. 

There is not enough room in memory to open a list, try again later. 

The list is already opened. 

The variable list pointer is NULL. The list is not opened. 
List open but not connected, no write access. 
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ENOADDTBL List is marked as having been optimized. There is a NULL poincer instead 

of a Netwo rk Address Table, The list is no c opened. 

ENOSZND Not enough space co allocate message buffers. Lisc is open, buc remotes are 

not connected or scanned, local variables are being scanned. 

ENCAD RS? You specified a Network Address Table that is too small. The list is open 

but none of the remote variables are being scanned. Variables that fit in the 
table are being scanned (optimized version only). 

EiAXOPttS The omopen id table is full (maximum number of opens reached); list not 

opened. 

ESCANF til List open, but the local scanner database is full; variables that fit in the 

database are being scanned. 

EIPCRET You have an unspecified IPC error, other than ENOTACTTVE. 

Call Notes: 

1- Names in the open list should be uppercase to ensure reconnccuon. All the speci- 
fied variables are scanned," at the scanjate, for changes greater than or equal to the 
delta value. Those that change can be picked up with a dqchange or omread. 

2. The unoptimized version of this call saves space by using the O Ms address table. 
Your variable addresses are found and added each time you open the list. 

3. Use the openjd to issue the omclose call. It is imperative that the lists be closed 
before any exit from the program. 

4. Optimized is faster, but takes up more memory; unoptimized is slower but uses 
less memory. The first omopen is always unoptimized (since it has to find the net- 
work addresses). 

5- For lists with write access only, specify NO_NOTLFY and a large delta. This saves 
the overhead of unnecessary data reading, and saves, a change queue. 

3.4.1 Optimized and Unoptimized omopen calls 

Whether an omopen call is optimized or unoptimized depends on whether the network 
address tablejjointer (in the om_header_node structure) is null or not. For the faster, opti- 
mized operation you have to provide a Network Address Table in addition to the 
ora_header_node and a list of all the variables you will want to access. 
A list which does not have its own Network Address Tabic is not oprimizable. The 
om_header_node contains a NULL pointer instead of a pointer to an address table. When the 
list is opened, there is no information showing where on the network the variables should be 
found. Those not found locally will be sought and opened via a broadcast message. Because 
the list docs not have its own address table, the returned network addresses are temporarily 
recorded in the Object Managers address table as long as the list is open. (The OMs address 
table is used by multiple functions within the local station. The advantage is that no duplicate 
PSAP's need to be stored within the local station.) When the list is closed, the location infor- 
mation is discarded. 
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To prepare a. list for optimization (in anticipation of replaced o?nopenQ calls), you muse allo- 
cate memory for che address cable In che callers daca space. The cable may initially concain 
garoagc. The pointer co che cable, along with che currenc (zero) and maximum size values, is 
placed in che om_headar_nace. The firsc time che Use is opened, che locations of ics variables 
are noc known. Those chat arc found locally, and chose chat are found via che broadcast will 
have their corresponding PSAP s recorded in the Network Address Table belonging to che list. 
The list is then considered co be optimized. However, ic is only partially optimized if any vari- 
able was noc found by che rime che lisc is closed. The available locacion informacion is pre- 
served by che address cable (and variable list). The next time thc lisc is opened, this 
information is used to avoid broadcasting, and makes che processing considerably fescer. 

Thc relationships between the structures of open variable lists, both unoptimizable and opti- 
mizable, are shown below. 



*om_descriptor 




OPTIMIZED: 
For each ompen, supply the 
variable list. During the first 
omopen Object Manager will 
find the network address for 
each variable and build the table. 



variable 
list 



network 
address 
table 



When you call omclose, the Object Manager updates the information in the address table, vari- 
able list and header node. Save this daca, and che next time you omopen chis list, supply all 
three to greatly speed up thc call. (Do not change any of them!) 

For unoprimized operation, which takes up less memory, you just provide header node and a 
list of variables. The Object Manager will use its own address table. Create che lisc structure as 
follows: 



*om_descriptor 



network address pointer 




UNOPTIMZED: 
When omopen see this data 
structure it will use its 
own address table. 



variable 
list 



(NULL) 



801 93BC- October 31, 1995 (■ ) Section 3. C Calls V " f fJpdate Sets or Variables 

3-4.2 omopen User initialization 

Before calling ornopenQ, you mast be a registered user and activated with IPC for connection- 
less communicarion.Thc data structures associated with a list muse be allocated and initialized 
before die list can be oDened. 

The following definitions statically allocate space for an c:r._headar_ncda, a variabia_list 
and.a Network Address Table. A list with, ten elements permits connections to that many vari- 
ables. A list may contain up to 255 elements or variable address entries. The maximum size 
(five elements in the example shown below) is based on the number of stations (local and 
remote) in which any of the listed variables may be found. These structure definitions arc 
defined when the user includes cm_usar.h. 

The following C code fragments are examples of how you can set up your data structures: 

^include <om_user.h> 

main () 
I t 

| static 

| static 

| static 

J static int cpen_ic; 

The above example statically allocates a variable list of 10 elements (i.e., you wish to connect 
| to 10 variables) . It also allocates a header node and a Nerwork Address Table for five entries. 

The C code below initializes the list header node. This is an opdmizable list, since the pointer 
_ i to a Network Address Table, rather than a Null Pointer, is stored in the nat_adr_tbl_otr 
member of the header node. The address table is empty, as indicated by the current size of 

zero, but can hold up to the specified maximum number of address entries. 

The variable list structure is also linked to the header node. The current and maximum sizes 
of a list are the same unless there are unused entries at the end of the list. Such entries would 
used with the unopdmized lists. A maximum size of zero is logically equivalent to the speci- 
fied current size. 

List state information is kept in the header node. The list has an access mode of read-only, 
write-only, or read/write. The access mode codes are defined in om_user.h and one code 
f\ must be placed in the task_status member of the header node. 

The HTSXST_0 PM (optimization change flag) bit of the task status member must be initialized 
to zero to show that the list is not optimized. (This is accomplished below in the process of 
storing om_r_accsss.) 

The scanner update frequency is specified in the list header. The 16-bit scan rate member of 
the header node is divided into a scan delay high byte and a scan rate low byte. The scan delay 
byte contains the number of half-seconds between the first and second scanner updates. The 
scan rate byte contains the number of half-seconds between updates thereafter. A scan delay of 
zero means that all scanner updates will occur at the specified scan rate. 



srruct om_heacer_node 
struct ocsn_var 
struct R3t_adr 



cra_descriptcr; 
variable_lisc [10 ] ; 
nat_adr_thl[5] ; 
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Undefined bics and fields in che header node are reserved by che Object Manager and muse be 
set co zero. Among these are bics in che cask.scacus and scacus.exe. 

The following code example is for secring up che structures: ■ 

byte.fiH {& om_cescriptor. 0, size off (struct om_header_ncde) ) • 

cm_cescriptor.tasfc_seatus = 0M_R_ACCZ55 ; 

om _descriptor.status_ext = 0; 

om_descriptor.sca.i_raea = (0 « 8): 3 ; 

ora_descriptor.ocen_lise_per = variable_lisc ; 

om_descriptor.cur_size_ocar._lise = 10; 

ora_descriptor.max_size_open_list = 10; 

cm_descriptor.r.et_adr_ebl_pcr = net_adr_tbi ; 

om_descripcor.size_net_adr^cbl = 5; 

This set3&dr_tbl_pcr co poinc co che nccwork address cable. Nocice chac as a resulc of che 
ensuing c\rnopencdl che Use becomes optimized, because net_adr_tbl_ptr is noc NULL. 
This a^o s C ^rj Jpen _ list ._ DCr CQ poim tQ ^ vaikb , c lisZ) sccs ma2dmum and cufrenc 
-sizes of che network address cable co 5 and 0, respectively, secs-che maximum and currenc sizes 
or variables list co 10 and 10, and sets che access co read only. Accually. che sizes can be any- 
thing you wish. 7 

om_r_acc£ss, om_w_acczs3, and om_rw_acc2SS are all defined via che include file. 
The following code example is for secring up the variable list: 

scrcpy (vatiable_list[0] .name, name) ; 

variable_list[0] .var_cesc = NOTIFY; 

variable_lisc[0] .delta = delta.value; 

variable_lisc[0] .var_stae =0 

This example sets up che variable lisc jusc for elemenc zero. You would have to set it up for all 

elemencs you wane co connect co, buc noc necessarily all of che elemencs in che lisc. 

The Null-terminared variable name scring is copied inco che name member. Names should be 

encered in uppercase. The NOTIFY op dorf is specified in che var.desc member, and che 

change driven delca value is scored in che delca member. . x 

The following code opens che lisc. The lisc is specified using che address of che header node 
scruccure. The ID of che opened lisc is returned, along wich any resulting error code. 

result = cinopenf&ora.cescricrsr, &ope.n_id) ; 
No furcher initialization is needed co reopen a lisc (optimized or noc) after ic is closed. 
Ic ts esscncial chac, aside from initialization, you do not alccr these scruccures once che lisc has 
been opened, excepc chrough Objecc Manager calls. This is especially true for an optimized 
lisc, even when closed, if ic may be opened again. 
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3.4.3 omopen Connections 

When a list containing optimized remote variables is opened, a connectionless send of a 
omopen message goes to each remote station believed to have some of the opdmized variables. 
The message consists of one or more packets. A packet contains a copy of the list header as 
well as the list entries for as many variables as will fit in the packet. 

When a station receives an -omopen packet, the packet is processed by the server_omopen rou- 
tine. This routine allocates, initializes, and opens a new list of the variables specified in the 
omopen packet. If the list has already been opened, the list is extended to contain the variables 
specified in this latest packet. The list already exists if the packet was not the first packet 
received for the omopen message. The list would also exist if an open broadcast message had 
already been received for the same list. 

The variables specified by the omopen packet are expected to be local to the st ation to which 
the packet is sent. The variables when located, are added to the scanner database, and secured 
if the list is used for write access. 

3.4.4 omopen Server Broadcast_ 

When a list containing unoptirnized remote variables is opened, a connectionless broadcast of 
an omopen broadcast type message is issued. The .message consists of one or more packets. 
Each packet contains a copy of the list header as well as the names and some information 
about as many of the non-local variables will fit in the packet. 
When a station receives an omopen broadcast packet, the packet is processed by the 
server_omopen_bcast routine. This routine allocates, initializes, and opens a new list of the 
variables specified in the broadcast omopen packet. If the list has already been opened, the list 
is extended to contain the variables specified in this latest packet. The list already exists if the 
packet was not the first packet received for the broadcast message. The list would also exist if 
an omopen message had already been received for the same list. The variables specified by the 
broadcast packet are searched for locally. The variables, when located, are added to the scanner 
database, and secured if the list is used for write access. 

A remote station knows when it has received all of the omopen and open broadcast messages 
for a particular list. The total numbers of opdmized and unoptirnized variables to expect are 
contained in every message packet. When enough message packets are received to account for 
all of these variables, and when these packets have been processed, the remote list is consid- 
ered opened. • 

Once the remote copy of the list is complete, the remote station sends an open return type 
message back to the original station. This message indicates that the remote open has been 
completed, whether there were variables that were found, and whether the open railed. 
No remote list is created if the station does not have any of the variables represented in the 
message packets. If any omopen message packets (representing optimized variables) were 
received, the open return message is sent even if none of the optimized variables could be 
found. If a station receives only open broadcast message packets (representing unoptirnized 
variables), and does not have any of the variables, it will not send an open return message. 
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3.4.5 omopen Server Return 

The server^omopen^return routine processes che omopen return message when it is received by 
the original station. The corresponding list is found. If the list is optimized, the key.code from 
the remote station is compared against that in the corresponding entry in the Network 
Address Table entry. If the key code has changed, the optimization change bit is set, and the 
Network Address Table is updated. 

Error status from the remote list is checked and incorporated into the status of the master 
(local) copy of the list. If there was an error, any relevant change-driven variables are flagged, 
and the list is posted to the change queue. 

Entry information needed from the remote list is copied into the master list. The count of sta- 
tions which have not yet responded to the omopen message is decremented, if appropriate. 
The count of unoptimized variables which have not yet been accounted for is also decre- 
mented, if appropriate. 

If the list has become optimized, the link open variables list is called to set up the network 
address links. 
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3.5 omread - Read Values From Opened list 

omread reads variables from che Use opened with die omopen call. This call allows you co read 
all or any part of che lisc You can read pares of che lisc in any order. This call is asynchronous 
You muse check die s ranis in che value structure co validate the data's integrity. 
Format: 

int omread (<omopen_id>, <siza_lisc>, <var_lisc>) 
^ nt omopen_id; 
int size_list; 
struct value *var_list; 



Where: 

oraopen^id 

size_list 

*var_list 

value 



index 



status 



T he op en id returned by che omopen calL 

The number of value structures in the list. 

A pointer co che value array structure. 

An array of structures containing che following elements:. 

struct value ( 

int index; 
unsigned int status; 



union 



{ 

char 
int 
long 
float 



letter; 
word; 
Icngint; 
fpoir.c; 



} uval ; 



}; 



The index value into the variable list corresponding to the variable that 
changed. 

The data type and status of the variable that changed: 



0 = This value not read yec, check for error 

Data cype - bits 0 to 4: 
1= CHARACTER 5 = BOOL 

2 = INTEGER 6 = OM_LNG JNT or POINTER 

3 = FLOAT or REAL 9 = OM.PACKED JOOL 

4 = STRING 10 = ONLLONGJ?ACKED_BOOL 

Error status — bits 5 co 7: 

0 = No response 4 = Bad daca type (scring 

1 = Being scanned or unconnectable compound 



f 
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2 

3 



: Disconnected 
Deleted 



uval 

Return Codes: 

0M_SUCCE55 

ESSCURS 

EMOTOPENSD 
EREAD 

ECONNBAD 

ESCANFUL 

0M_EC3SY 

Call Notes: 



5-6 = (noc used) 
7 = Noc ser.c (error rs:urned) 

The actual value of the variable. 



The list has been read. 

Attempt to open a secured variable. 

List is not opened (or bad om_descriptor). 

The omopen call was set for wrice only. 

Unable to connect to remocc station. 

List open, local scanner database too small; variables chat fit in the database 
are being scanned. 

Connection was busy on at least one station. The others are opened There 
is no auto-reconnect. 



1. For mulciple errors, the return code shows only one. EREADERROR is suDer 
ceded by ESCANFUL, which is superceded by ECONNBAD. 

2. To only read part of the list, you can specify che order. If you read the whole list it 
- reads m ascending order. 

3- If one of the status values is zero, that variable has not been read (or pcrhaos 
scanned) yet, or there is a problem such as bad data type or variable not found. 
CCk for 111 error r«urn. In any case, uval does not contain a legitimate value. 
4. If you wish to tead all variables in the open list, match sizejist to che size of chc 
open list. Do not set the individual indices. The Object Manager reads the list in 
ascending order of index number. 
5- There ts a macro, v_varlist(s), that statically or dynamically allocates the value 
structure for you. This macro is defined in the om_user.h include file as: 

^define v_varlist(s) valloc (sizecf (struct value) -s) 
The following is an example of how this macro could be used: 
size_list = 10; 
value_list = v_varlist<10) ; 

if (value_list == (struct value ') MULL ) 
( 



The first line sets the sizejist calling argument. 1 he second line dynamically allo- 
cates a 10-element array of "value" structures. If you use this macro, be sure to free 
che memory when che structure is no longer needed. It is also advisable co check 
that chc macro did noc return a NULL pointer indicating insufficient available 
memory. 
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3,6 omwrite - Write Values to Opened List 

omwrite writes variables co che list opened with the omopen call. This call allows writes to any 
or all entries in a list, omwrite is asynchronous if the variable is not in the local station; it ini- 
tiates the omwrite message and returns control to your process/ task. 

gerjal can verify any omwrite regardless of the delta. If the write changes the value by the vari- 
able list delta, it can be verified by either of two ways: 

1. If the variable NOTIFY option is set, use dqchange or dqlistzo verify the write. 

2. An omread issued after the list scan rate period can also be used. 
Format: 

int omwrite (<oraocen_id>,<si23_list>,<var_list:>) ; 
i nt omcpen_id, size_list; 

struct value *var_list:; 

Where: 

cmopen_id The openjd returned by the omopen call. 

size_list The number of value structures in the var_list. 

*var_list A pointer to the struct value array. 

A value structure contains che following elements:. 

struct value { 

int index ; 

unsigned int status; 
union { 

char letter; 

int word; 

long longint; 

unsigned int uword; 

unsigned long ulong; 

float f point; 

} uval; 

} ; 

Where: 

index The number (0 base) of the variable list entry to be written. 

s ^£us The data type of the variable (low order byre filled in by the caller). 

An error return code (next to low order byte): 

1 = Variable not on scan 

2 = The user specified data cype does not match the actual data type. 

3 = The index is <0 or greater than the size of the list. 

uvai The value to be written. 

Return Codes: 
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OM_sacczss 

HNOSPACZ 
ENOTOPENED 

ESECC7RE 



The list has been wrirren. 

Sysrcm resource availabiliry problem. 

The specified list has nor been opened successfully. No wrires are per- 
formed. ' " 



EWRITE 
0M_EC3SY 

ECONNBAD 



The specified lisr has nor been opened successmily because a variable in rhe 
lisr has been secured by another open lisr. No wrires are performed. 
The lisr is opened for read-only access. No wrires are performed. 

The lisr was nor opened successfully because one or more server srarions 
have used up all its ailorrcd IPC channels. No wrires are performed. 

The lisr was noc opened successfully due ro one of rhe following 

1. A remore scanner dara base is full. 

2. Optimized rrewerk address rable is full. 

3. IPC send problems. 

No writes are performed. 

Noc all remore variables in rhe list have been found/opened No wrires are 
performed. 

The size of ch c wrire variable array is < = 0 or grearer rhan the size of the 
open lisr. No wrires are performed. 

An IPC error was encounrered when sending an omwrire message ro a 
remore server starion. Variables may have been written ro orher srarions. 
For each variable in rhe wrire list, validiry checks are performed. If an error is encounrered, an 
error code is set in the high byte of the callers write list variable status. All variables are 
checked, even if an error condition is encountered in the loop. An EWAIT return has prioriry 
over EWRTTERROR. If any error is encounrered no wrires are performed. 

A variable is nor on scan. The (wrire lisr variable starus) error code is ser co 



ESTATION 



ZOMWSIZZ 



ENOT ACTIVE 



EWRITEERROR 



EWRITEERROR 



EWRITEERROR 



Call Noces: 



The wrire lisr variable type (ser in srarus) does nor march rhe open lisr vari*? 
able rype. The error code is set to 2. 

The write list variable index is grearer rhan rhe size of the lisr (header 
cur_size_open_lisr). The error code is set ro 3. 

A CP wrire error has occurred. Variables may have been wrirren co ocher 
srarions. The error code is sec co 4. 



1. If you only wrire part of che lisr, you can specify che order by index number. If you 
wrire tr all, (sizejisr is rhe same size as rhe open lisc) ic writes in ascending order 
regardless of index numbers. 

2. If one of rhe srarus values is zero, char variable has noc been read (or perhaos 
scanned) ycr, or rhac there is a problem such as bad dara type or variable noc 
found. Check for an error return. In any case, uval does noc concain a legitimate 
value. 0 
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3. If you wish co write all variables in chc open list, macch size_lisc co che size of che 
open lisc. Do noc set: die individual indices. The Objecr Manager writes che Use in 
ascending order of index number. 

4. There is a macro, v_varlist(s), that statically or dynamically allocates che value 
structure for you. This macro is defined in che om_user.h include file: 

^define v_varlist (s) valloc (sisacf (struct value) *s) 
The following is an example of how this macro could be used: 
size_list = 10; 
value_list = v_varlist (10) ; 
if (value_list == (struct value *) MULL } 
{ 

} 

The first line sets the size_list calling argument. The second line dynamically allo- 
cates a 10-element array of "value" structures. If you use this macro, be sure co free 
che memory when che structure is no longer needed. It is also advisable to check 
chac the macro did not return a NULL pointer indicating insufficient available 
memory. 

5. iMasks are not specified for data types OM_SJPKBOL and OM_L_PKBOL. 
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3./ omwrstat - Write Values and/or Status to Opened 
List P 

omwrstar v/rizcs variable data and/or status co a list opened with the omopen call. This call 
allows writes co any or all entries in a list, omvmtatls asynchronous if the variable is not in the 
local station; it initiates the omwritc message and returns control to your process/task. 
gerjalczsi verify any omwrite regardless of the delta. If the write changes the value by the vari- 
able list delta or changes the status, it can be verified by either of two ways: 

1. If the variable NOTIFY option is set, use dqchangeot dqlisz to verify the write. 

2. An omrcad issued after the list scan rate period can also be used. 
Format: 

inc omwrstat {<omopen_id>, <size_list>, <var_list>) ; 
lrit cmc?er._id, size_list; 

struct valstat *var_list; 

Where: 

omcperi-id ; The open_id returned by the omopen call. 
size_list The number of valstat structures in the varjist. 

* var -l is t A pointer to the struct valsrat array. 

A valstat strucrure contains the following elements:. 

struct valstat { 



int 


index; 






unsigned int 


status; 






unsigned int 


setstat ; 






unsigned int 


setsiask; 






unsigned int 


setonly; 






union 


{ 








char 




letter; 




int 




word; 




long 




longint; 




unsigned 


int 


uword; 




unsigned 


long 


ulong; 




float 




fee int; 



} uval; 



Where: 

index 

status 



The number (0 base) of the variable list entry to be wricten. 

The data type of the variable (low order byte filled in by the caller). 
An error return code (next to low order byte) . 
1 = Variable not on scan. 
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satraask 

setonly 
uval 

Return Codes 
CM_SUCCZ53 
ENOSPACS 
ENOTOPENED 



2 * The user specified data cype does noc march chc acrual data type. 

3 = The index Is <0 or greater than che size of che list. 

4 = Setmask contains invalid bits.. 

The bit settings of those bits specified to be written in setmask. 

The status bits to be written or NULL. Valid bits are OM_STAT_BAD 
and OM_STAT_OOS as defined in OM_UDEF.H. 

If TRUE, write status only for this yalstat entry. Ignore uval. 

The value to be written. 



ESECURE 

EWRITE 
0M_EC3SY 

EC0MN3AD 



No error. 

System resource availability problem. 

The specified list has no been opened successfully. No writes are per- 
formed. 

The specified list has not been opened successfully because a variable in the 
list has been secured by another open list. No writes are performed. 

The list is opened for read-only access. No writes are performed. 

The list was not opened successfully because one or more server stations 
have used up all its allotted IPC channels. No writes are performed. 

The list was not opened successfully due to one of the following: 

1. A remote scanner data base is full. 

2. Optimized network address table is full. 

3. IPC send problems. 
No writes are performed. 

Not all remote variables in the list have been found/opened. No writes are 
performed. 

The size of the write variable array is < = 0 or greater than the size of the 
open list. No writes arc performed. 

An IPC error was encountered when sending an omwrite message to a 
remote server station. Variables may have been written to other stations. 

For each variable in the write list, validity checks are performed. If an error is encountered, an 
error code is set in the high byte of the callers write list variable status. All variables are 
checked, even if an error condition is encountered in the loop. An EWAIT return has priority 
over EWRJTERROR. If any error is encountered no writes are performed. 

EWAIT A variable is not on scan. The (write list variable status) error code is set to 



ESTATION 



EOMWSIZS 



ENOTACTIVE 



1. 



EWRITEZRROR 



The write list variable type (set in status) does not match the open list vari- 
able type. The error code is sec to 2. 
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EWRITESRRCR The wrice lisc variable index is greacer chan che size of the list: (header 
cur_size_opcnJist). The error code is se: co 3. 

EWRITEZRROR The sctmask concains bits sec other chan OM_STAT_OOS or 
OM_STAT_OOS. The error code is se: co 4. 

CallNoces: 

1. If you only wrice parr of che lisc, you can specif/ che order by index number. If you 
wrice ic all, (sizejisc is che same size as che open lisc) ic writes in ascending order 
regardless of index numbers. 

2. If one of che scacus values is zero, chac variable has noc been read (or perhaps 
scanned) yec, or chac cherc is a problem such as bad daca cype or variable noc 
found. Check for an error recurn. In any case, uvai does noc contain a legicimace 
value. 

3. If you wish co wrice all variables in che open lisc, macch size_lisc co che size of che 
open lisc. Do noc sec che individual indices. The Object Manager writes che lisc in 
ascending order of index number. 

4. There is a macro, v_varlist(s), chac scacically or dynamically allocaces che value - 
structure for you. This macro is defined in che om_user.h include file: 

^define v_varlist (s) valloc (sizeof (struct value) *s) 
The following is an example of how this macro could be used: 

size_list = 10; 

value_list = v_variisc (10) ; 

if (value_list == (s cruet value *) NULL) 

{ 

} 

The first line sees che sizejisc calling argument. The second line dynamically allo- 
caces a 10-element array of "value" scruccures. If you use chis macro, be sure to free 
the memory when che scruccure is no longer needed. Ic is also advisable co check 
chac che macro did noc recurn a NULL poincer indicating insufficient available 
memory. 

5. Masks are noc specified for daca cypes OM_S_PKBOL and OM_LJ?KBOL. 
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4. C Calls to Locate and Catalog 
Objects 

Locating an object means getting ics address. Cataloging means installing or removing objects 
from the object directory or the import list. 

The object directory contains all the shared objects created by the casks in the local s radon. 

The import list contains the names of all data objects that tasks in che local station want co 
import from remote stations. Listed with each name is an index value into che address cable, 
which contains the address of the named object. 

The OM C calls co locate and catalog objects are listed in chis Section in alphabetical order 
and summarized in Table 4-1. 



Table 4-L C Calls to Locate and Catalog Objects 



Paragraph 
No. 


Call 


Function 


4.1 


globaLfind 


Find and objects address 


4.2 


import 


Add objecc to import list 


4.3 


obj_create 


Add a new object to che directory 


4.4 


obj_delece 


Delete from object directory 


4.5 


obj_m ul t i_create 


Add multiple objects co che director/ 


4.6 


unimport 


Remove object from import list 
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4.1 globaljind - Find an Object's Address 

The global Jind call finds an object and returns ics address. This call is synchronous' che call 

suspends until che operation is complete. 

Format: 



inc fflobal_ffiad(<obj_naaa>,<cbj_ty?6>,<?sa?jcr>) 
c ^ ar *obj_iiaae; 
lrxc obj_type; 
PSAP^ADDR *?sa?_pi:r; 



Where: 
*obj_tiaine 
obj_type 



*?sap_ptr 



A pointer to the name of the object to be located. 

The objects type, which can be one of che following: VARIABLE, ALIAS 
PROCESS, or DEVICE. 

A pointer to the location where glofaal_f inc returns che objects station 
address. 

Return Codes: _ 
OM.SUCCZSS 
EBADTYPE 
ENOTFOUND 
E3ADNAME 
EN0SPACZ 
EIPCRZT 
Call Note: 

The address buffer is modified if the call fails. Be sure to check for an error return 
before using the address. 



The call successfully returned a valid address. 
The specified object cype is invalid. 
The named object could noc be found. 
The object name is invalid. 
There is a memory allocation error. 
An unspecified IPC error. 
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4-2 import - Add Object to import List 



The import call adds a remote object co die local stations import list. The imvonc&X is syn- 
chronous; your task suspends until die call is complete. 
Format: 

int import (<nasie>, <obj_type>) 



cnar 
int 

Where: 
*name 

Return Codes: 

om_succzss 

ebadtype 

Z3ADMAME 

ENOTFOUND 

ENOSrACE 

ELOCAL 

EIMPFULL 

EIPCRET 

Call Note: 



*name; 



A poincer to the name of the object to be imported. 

The objects type, which can be one of the following: VARIABLE, ALIAS 
PROCESS, or DEVICE. 



The object is now on che import list. 
The specified object type is invalid. 
The specified object name is invalid. 
The object name cannot be found. 
There is a memoty allocation error. 
The object you are crying to import is local. 
The import list is too full to add your object. 
An unspecified IPC error. 



If you move an object of cype PROCESS or DEVICE, the import table is not 
updated. You must unimport, then import these object types to make sure you have 
the most current address. 
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43 obj_create - Add a New Object to the Directory 

The ofy^creareadl adds a shared object co che object directory and automatically makes ic glo- 
bal. This call is synchronous; your cask suspends uncil che call compleces. 
Format: 



int ohj^crsats 
char 
int 

Where: 
*naiae 

var_type 



str_len 

Return Codes: 

OM_SUCCZSS 

ESTRLZN 

E3ADTYPE 

E3ADMAM2 

EDUPLICATE 

E03JPND 

EIPCRZT 

ENOSPACE 



i{<nani5>, <cbj_type>, <var_ty?e>, <2tr_ler.>) 
*nan:e; 

ob j_type , var_t:y?e, scr_len; 
Apoincerco che objects name. 

The objects cype, which can be one of the following: VARIABLE. ALIAS 
PROCESS, or DEVICE. 

The daca cype of che objects value, which can be one of che following 
CHARACTER, INTEGER, FLOAT, STRING, OM_LNG INT, °* 
OiVLBOOL, OM_S_PKBOL, or OM_LJ?KBOL. 
An alias jnust be of variable type STRING. var_typ e should be zero for 
object cypes PROCESS and DEVICE. 

The string length for VARIABLE and ALIAS objects. 

The new object is now in the object directory ■ * 

The string length is invalid. 

Either the object or data cype is invalid. 

The specified object name is invalid. 

That object name already exists in the directory. 

Thac object is being created by anocher cask. 

An unspecified IPC error. 

No memory available, cry again lacer. 
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4.4 obj_delete - Delete From Object Directory 

cne request then immediately returns control to your cask. 
Format: 

inc ob5^del*c«(<nas»> # <obj_typa>J 



cnar 
inc 

Where: 

Return Codes: 

0M_SUCC2SS 

E3ADNAMH 

E3ADTY?E 

ENOTFOCJMD 

Call Note: 



'name; 



A pointer to che name of che object co be deleted. 

The objects cype, which can be one of the following VARIABLE ALIAS 
PROCESS, or DEVICE. ' ~- 4nj| 



The request has been initiated successfully. 
The specified object name is invalid. 
The specified object cype is invalid. 
The specified object is not in the directory. 



If a deleted object was connected, it becomes disconnected and any task cryin* co read 
or write it is notified that it is disconnected (in the status part of the value structure) 
ance there is no error or warning returned when this happens, it is up to you to make 
sure you do not delete the wrong objects. 
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4.5 obj_multi_create - Add Multiple Objects to the 
Directory 

The obj_multi_create call adds multiple shared objects co die object directory from a single 
Object Manager call. All objects are verified for uniqueness, and all objects share a common 
network timeout period. This call is synchronous; your cask suspends until the call completes. 

Format: 

int obj_mulei_craate (<obj_pcr>, <nura_cbjeces>) 
struct object_plus *objecc_ptr 
inc nura_objs 

"Where: 

ob j_ptr : The objects pointer ro the array of cb j ec=_plus object defmirions struc- 
tures (fro m om_ucac . h) 

obj6ct_ptr->nams[ ]: 
* NAME_LEN+1 alphanumeric characters of the objects name 

ob j ect_ptr->ob j ec=_typa: 

Objea type (VARIABLE, ALIAS, PROCESS, DEVICE, etc.) 
ob j ect_per->cy?e: 

The data type of the object's value, which can be one of the following: 
CHARACTER, INTEGER, FLOAT, STRING, OM.LNGJNT, 
OM.BOOL, OM_S_PKBOL, or OM_L_PKBOL. 

object_ptr->str_len: 

If the type is STRING, the string length. 

num_ob j eces: The number of objects to be created (< or - MAX_REG_SIZE from 
om_ucef.h) 

Outputs: 

object_ptr- >sc,atus : 

object_plus structure member updated for each object of the array 

Return Codes: 

om_success The new object is now in the object directory 

The following returns might be considered warnings, and as such, some of the objects in the 
array could have been created. In the event more than one of them has occurred, they arc 
returned in the order listed. 
ENOSPAcs The object directory is full 

EOSJPND The object in the array is a duplicate of an object pending creation 

EDUPLICATE An object in the array is a duplicate - local o r remoce 
The following errors are considered syntactical errors and prevent all objects from being cre- 
ated. 

E3ADTYPE Either the type is ouc of range or invalid for the object type 
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E3 AD make The specified object name has a non-alphanumeric charterer, or was coo 

long 

ESTRLZN A STRING variables str_len was improper 

E?ORT Objccr Manager internal error 
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4.6 unimport- Remove Object From Import List 

The unimport call removes an object from che local stations import list. The unimport call is 
asynchronous; it iniciaces che request then immediately returns control to your cask- 
Format: 

unimport !<name>, <ob j_ty?e>) 



cnar 
inc 

Where: 

"najae 

cbj_type 

Return Codes: 
CM_SUCCZSS 
EHADTYPE 
E3ADNAME 



*naine; 
ob j_ type; 



A poincer co che name of che object to be removed. 

The objects type, which can be one of che following: VARIABLE, ALIAS, 
PROCESS, or DEVICE. 

The object was successfully removed. 
The specified object type is invalid. 
The specified object name is invalid. 
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5. FORTRAN Functions to Get/Set 
Object Values 

1 hese functions reed and wricc object values. The/ are connectionless functions, best suited 
for sicuacions in which you wane a single transfer of data. As explained in the document on 
Inter-Process Communications, connectionless functions are functions chat transfer data 
between tasks without having first established an IPC connection (channel). The Object 
Manager registers your task with IPC for connectionless service. Be sure to declare the data 
type of the function name if you are interested in checking possible error returns. 

FORTRAN Object Manager programs for the AP10/AP20 I/A Series stations use a 16-bit, 
tnteger*2 for object values. The format for each function described below uses the incer*2 for 
object values. 

FORTRAN Object Manager programs for the 50 Series Application programs must adhere to 
the following conventions: 

♦ All integers must be either INTEGER or INTEGERS (not INTEGER"!). 

♦ Access to OM Control and I/O BOOLEAN Variables must be made through the 
50 Series FORTRAN compiler type: BYTE. 

To compile FORTRAN programs on 50 Series processors, use the command string: 

f77 tst.f -If ox -10M77 
The FORTRAN functions to get/set object values are listed in this Section in alphaberical 
order and summarized in Table 5-1 . 




Table 5-2. FORTRAN Functions to Get/Set Object Values . 



Paragraph 






No. 


Call 


Funciion 


5.1 


GETVAL 


Gee che value of an objec: 


5.2 


SETCON 


Se: che value of an objec: 


5.3 


SETVAL 


Sec che value of an objec: 
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5.1 GETVAL - Get the Value of an Object 

Use GETVAL to raid the value of a specified object. This function works for shared variables, 
process variables, and aliases. GETVAL is synchronous; it suspends your cask until GETVAL 
completes. 

Format: 

X = GETVAL (<r.ame>, <obj cyp ••, <in:?orc>, <value>, <scacus>, cacia-} 



integer*2 
character* 33 
integer*2 
character** 
(or real 
(or integer 
(or integer*2 



GETVAL 

na^e 

import, 

value 

value ) 

value) 

value) 



status, da tier., objcy? 



Where: 
name 
objtyp 
import 

jvalue 
status 



catlen 

Return Codes: 

OiCSUCCESS 

ENOTFOUND 

E3ADTYPE 

ENO SPACE 

E3ADMAME 

EE AD L EM 

TO.BIG 

ENO VALUE 



The name of the object. 

The named objects type; VARIABLE or ALIAS. 

1 = place the objects name on the import list. 
0 » do not place it on the import list. 

The objects value. Specify its size in bytes using daden. 

The objects status (data type). An ALIAS object type can only have charac- 
ter data type. 

The regular shared VARIABLE object type can have a data type of CHAR- 
ACTER, INTEGER, INTEGERS, or REAL. 

The Object Manager does not restrict process VARIABLE data cypes, but 
they can be of types CHARACTER, INTEGER, INTEGER*!, and 
REAL. 

Integers are signed, unless the block parameter definition specifies ocher- 
wise. Reals adhere to the IEEE standard. 

The length (bytes) allocated for "value." 
No errors. 

Object noc found (locally or globally). 
Illegal object type. 

No memory available; no value returned. 
Invalid object name. 
Shared variable is coo big for daclen. 
Process variable is too big for daden. 
Specified object cype has no value. 



on 
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ESAdvrec Value is corrupc, invalid daca type. 

EIMPFULL The import lisc is full; value returned, buc noc added co list. 

Ej-Pcrst You have an unspecified IPC error. 

Call Notes: 

1- Placing a local object (one found in chc same stacion) on che import list is unneces- 
sary, so for local objects GETVAL ignores that option. However, che value is still 
returned. 

2. Return code ENOTFOUND might mean that che object does noc exist locally or 
globally. If che object exists in a remoce scarion, chen chac stacion mighc be down. 
In either case, The Object Manager removes che object's name fromdie import 

3. If you do not make daden large enough, value will be coo small co hold che 
returned value. In such a case GETVAL returns as much daca in value as will fit. 

4. If datlen is too large, value will contain unused bytes. GETVAL does noc close-uo 
this unused memory space. 
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5.2 SETCON - Set the Value of an Object 

SEl CONsets the value of a specified object and waics for confirmation chat ic was sec. This 
call works for shared variables, process variables, and aliases. SETCOiVls synchronous; it ini- 
tiates the request then suspends processing until the operation is complete. 
Format: 

X = SETCON (<name>, <objtyp>, <import>, <value>, <scatus>, <dazler.>) 



integer*2 
character 
integer*2 
characters 
(or real 
(or integer 
(or intager # 2 



SZTCOM 
nasie 

import, datlen, status, cbjtyp 

value 

value) 

value) 

value) 



Where: 
name 
obj typ 
import 

value 

status 

cat 1 en 

Return Codes: 

OM_SUCCESS 

N0T_SETTA3LE 

SECURED 

ENOTFOUND 

E3ADTYPE 

ESECURE 

EN0SPACE 

E3 AD NAME 

E3TRLEN 

EMO VALUE 

EIMPFULL 



The name of the object. 

The named objects cype; VARIABLE or ALIAS. 

1 = Place the objects name on the import list. 
0 s Do not place it on the import list. 

The value to be set. Specify its size in bytes using datlen if it is a string or 
process variable. 

The objects data type. The possible data types are listed in FORTRAN 
Functions to Get/Set Object Values on page 79. 

The length (in bytes) allocated for "value." This is only needed for charac- 
ter data types and all process variables (regardless of data type). 

The value has been successfully set. 
This is not a settable process variable. 
Process variable secured; can't be set. 
Object not found (locally or globally). 
Illegal object type or data cype. 
Object is secured and cannot be set. 
No memory available; value not set. 
Invalid object name. 
The string length is invalid. 
Specified object type has no "value". 
"Value" is corrupc, invalid data cype. 
The imporc list is full; value set. 
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SIPCRET You have an unsoecified IPC error. 

«. 

TO_RZAL_CONV_ERROR 

Process-variable type-conversion error. 

TO_INTECER_CONV_EREOR 

Process- variable type-conversion error. 

TO_STRING_C0NV_EREOR 

Process- variable type-conversion error. 

TO_BOOL_CONV_ERROR 

Process- variable type-conversion error. 

Call Notes: 

1- Placing a local object (one found in the same scacion) on the import list is unneces- 
sary, so for local objects SETVAL ignores that option. However, the value is still 
set. 

2. ENOTFOUND might mean that che object does not exist locally or globally. If 
the object exists in a remote station, then that station might be down. In either 
case, the Object Manager removes the objects name from the import list. 

3. If daden is too small, SETCON truncates the value co fit. 

4. If daden is too large, value will contain unused bytes. SETCON does not close-up 
this unused memory space. . . 
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5.3 SETVAL - Set the Value of an Object 

SETVAL sets che value of the specified object. This function works For shared variables, pro- 
cess variables, and aliases, SETVAL is asynchronous; it initiates che request then immediately 
returns control to your task. 
Format: 

X = SETVAL ( <r.ame>, <objtyp>, <impcrt>, <vaiua>, <s:=:us>, <daclan>} 



intager*2 


SETVAL 


character 


name 


integer*! 


import 


characters 


value 


(or real 


value) 


(or integer 


value) 


(or integer*?. 


value) 



Where: 
name 
ob j typ 
import 

value 

status 



datlen 

Return Codes: 
OM_SUCCZSS 
N0T_S£TTABLE 
SECURE 
ENOT FOUND 
E3ADTYPE 
ESECURE 
EMO SPACE 



The name of the object. 

The named objects type; either VARIABLE or ALIAS. 

1 = Place the objects name on the import list. 
0 - Do not place it on the import list. 

The value to be set. Specify its size in bytes using daden, if it is character or 
a process variable. 

The objects data type. 

An ALIAS object type can only have character data type. 
The regular shared VARIABLE object type can have data types of CHAR- 
ACTER, INTEGER, INTEGER*!, and REAL. 

The. Object Manager does not restrict process VARIABLE data types, but 
they can be of types CHARACTER, INTEGER, INTEGER"!, and 
REAL. . 

Integers are signed, unless the block parameter definition specifies other- 
wise. Reals adhere to the IEEE standard. 

The length (in bytes) allocated for value. This is needed only for charac- 
ter data types and all process variables (regardless of data type). 

The set request has been initiated successfully. 
This is not a settable process variable. 
Process variable secured; cane be sec. 
Object not found (locally or globally). 
Illegal object type or data type. 
Object is secured and cannoc be set. 
No memory available; value not sec. 
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E3A0NAME Invalid object name. 

ESTRLZN The string length (datajen) is invalid. 

ENOVALUE Specified object type has no "value". 

E3ADVREC • "Value" is corrupt, invalid data type. 

EIxMPFULL The import list is full; value set. 

EIPCRZT You have an Unspecified IPC error. 

TO_REAL_CONV_ERROR 

Process-variable type-conversion error. 

TO_INTEGZR_CONV_ERROR 

Process-variable type-conversion error. 

TO_STRING_CONV_EaROR 

Process- variable type-conversion error. 

T0_300L_C0NV_ERR0R 

Process- variable type-conversion error. 

Call Nares: 

1. Placing a local object (one found in the same station) on the import list is unneces- 
sary, so for local objects SETVAL ignores that option. However, the value is still 
sec. *" " " " 



^' ENOTFOUND might mean that the object does not exist locally or globally. If 
chc object exists in a remoie station, then chat station might be down. If so, the 
Object Manager removes the objects name from the import list. 

3. If daden is too small, SETVAL truncates the value to fit. 

4. If daden is too large, the value will contain unused bjnres. 
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6. FORTRAN Functions to Access/ 
Update Sets of Variables 

These calls allow your cask co establish a delca value for each of a Use of process variables (using 
OMQPEN). The delta value is how much change has co cake place in die variables value 
befo re your cask is nodfied (by DQCHNG). 

The variables in an opened list are maintained locally so chac che response on reads is immedi- 
ate and requires no network traffic. These calls are designed for casks needing ongoing access 
to many process variables. 

A task can read from or write co variables on a list opened with O/V/OPfNuntil the occur- 
, rencc of undl issuing an OMCLOS, call, at which rime the Object Manager returns a table of 
. addresses where it found the variables. Subsequent OMOPENs can use the same table of 

addresses, thus saving processing rime. 

FORTRAN Object Manager programs for the AP10/AP20 I/A Series stations use a 16-bit, 
intcger m 2 for object values. The format for each function described below uses the inter" 2 for 
object values. 

FORTRAN Object Manager programs for the 50 Series Application programs must adhere to 
the following conventions: 

♦ All integers must be either INTEGER or INTEGERS (no c INTEGERS). 

♦ Access co OM Control and I/O BOOLEAN Variables must be made through the 
50 Series FORTRAN compiler type : BYTE. 

In addition, when performing reads/writes of OM BOOLEAN types in lists, a four BYTE 
array must be EQUIVALENCEd to an INTEGER, as shown in the following example: 

BYTE BYTZVAL ( 4 ) 

INTEGER INTVAL 
EQUIVALENCE (3YTEVAL, INTVAL) 

OMREAD (OPENID, NUMVAR, INDEX, STATUS , INTVAL) 

then co access the byte, reference elemenc 0: 
VALUE = BYTEVAL ( 0 ) 

The FORTRAN functions to access/update sees of variables are Wsizd in chis Section in alpha- 
betical order and summarized in Table 6-1. 
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Table 6-1. FORTRAN Functions to Access/Update Sets of Variables 



Paragraph 
No. 


Call 


Function 


6-1 DQCHNG 


Chsck for object value changes 


6-2 | OMCLOS 


Close die soecified variable lisc 

* 


6-3 OMOPEN 


Open a sec of variables j 


6.4 


OMREAD 


Read values from opened lisc 


6.5 


OMWRI 


Wrice values co opened lisc 



f ; { ) 
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6.1 DQCHNG - Check for Object Value Changes 

The DQCHNG function checks co see If any values in an/ OMOPENed variable lists have 
changed. Ic checks all die lists for die cask named and returns changes in die first variable lis: 
ic finds. In order co register as a change, die new value has co be greater than or equal co che 
dclca value (in OMOPEN) for chat value. To be notified, set che notify option in OMOPEM. 

Format: 



DQCHNG (<: 

intager*2 

integer*2 

integer*2 

integer*2 

intager*2 

integer*2 

integer 

integar*2 



Where: 

flag 

ocenid 

qsize 
qindex(y) 

qs tatty) 
value (y) 



lag>,<openic>, <csize>, <qiadex>, <qstaz>, <value>, <rqsiza>) 

DQCHNG 

flag 

openic 

qsize 

qindex(y) 

qstat(y) 

value (y) 

rqsize 



0 = done suspend, 1 = suspend. 

A value returned to the caller chac identifies a previous o mop en call whose 
list has changed. 

Number of elements in value array. 

Where y = csize, the index value inco the variable list corresponding to 

the variable that changed. 

An array of status of changed variables. 

An array of values for each entry in the list . value (y) must be declared 
in four bytes or floating poinc, even if the value is character data type. 

Example of a mixed variable type list: 
rqsizeThe number of ciemencs returned. 



Return Codes: 

OM_SUCC£SS 

SSSCURS 

ENCT OPENED ' 



character* 4 

integer 

real 

equivaler.ee 



charva (y) 
ival (y) 
raadva (y) 

{ charva , ival , raadva) 



Changed variables have been successfully returned. 

One or more variables in che lis: is secured, so dqchange will not work on 
chis lisc. 

The specified cask has no variables sec for notification access, or no opened 
liscs. 
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ecomnbad The OAf OPEN could noc establish an IPC connection. You should close 

che list. 

ZQNOTS&FTY The value array is coo small co hold all che changes chac che Object Man- 
ager has in its queue. 

EQ EMPTY You did noc specify che suspend opcion and chere were no changes in che 

Object Managers queue. 

Call Noces: 

1. You can specify any cask name (process id) chac has open lists. If more chan one 
open Use has chanees in ic, DQCHNG recurns che changes in che first list, then 
remove chat list from its queue. Use anocher DQCHNG call to get che changes in 
che next list. 

2. Each variable list is idencified by che open id returned when che lisc was opened. - 



on 
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6.2 OMCLOS - Close the Specified Variable List 

The OMCLOS call closes a list of local or remote variables by releasing che connection estab- 
lished with the OMOPENadL It also supplies all of the header information, variable list, and 
address cable to speed up fiicure OMOPEiValh to the same list. 

OMCLOS is asynchronous; it initiates the request then immediately returns control to your 
cask. 

Format: 

X = OMCLOS (<numvar>, <c?anid>) 

integers OMCLOS 
intagar*2 numvar 
incager*2 ccenid 



Where: 

nuinvar The number the number of variable names in the specified openid. 

ooenid The id from the previous OMOPEN. 
Return Codes: 

OM_stJCCESS The request has been initiated. 

ENOT opened There is no open list corresponding to c?an_id. 

EIFCRET You have an unspecified IPC error. 

Call Note: 

It is imperative thac che liscs be closed before any exit from che program. 
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63 OMOPEN - Open a Set of Variables 



The OMOPEN call opens a list of ud co 255 local or remote variables. You must use this call 
before using any of the other daca access calls. This call is asynchronous; it initiates the request 
then immediately returns control co your task. 
Format: 



X 



OMOPEN «aunwmr>. <nas»>, <d«lca>, <noti£y>, <rwacc>, <c?e:iid>, <scr. 



r.ra:» 



integar*2 
character* 3 3 
intager w 2 



intager~2 



GMOPEN 
name (y) 

auravar , 
delca (y) , 
notify (y) , 
rwacc, 

ccenic 
senrat 



Where: 

name An array of x names in the list. _ 

nunvar The number of variable names. 

delta An array of delta values; one for each variable name. 

notify An array of change notifications; one for each variable name. 

rwacc Read/write access for che list. 

ocanic An id returned co che- user. 

senrat The rate at which the station that gets the data sends it to the station that 

opened the list. This can be a value from 1 to 120 half-second intervals. An 
invalid scan race defaults to one (1/2 second interval). 
The FORTRAN call only uses the unopumized version, which cakes up less memory. You 
provide a list of variables, the Object Manager uses its own address cable. 

Return Codes: 

The lisc has been opened. 

One or more variables cane be found; che rest are being scanned. 
Actempt co open a secured variable; che list is open, but no wrice access co 
any variables. 

EHOSPACZ There is noc enough room in memory, cry again later. 

E0PSN2D The lisc has already been opened. 

EC0NNHAD List open buc noc connected, no wrice access. 

EN0ADDT3L Previous OMOPEN tot this list had an address cable; che lisc is open, buc 

noc scanned. 

SSOSSMD Lisc open, buc remote are noc connected or scanned, local variables are 

beins scanned. 



OM_SUCCZSS 

EMOTFOCjND 

E5ECURZ 



r 
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ssMMPsis The OMOPfNid able is foil; list not opened. 

ESCANful List open, but ch e bcal scanner database ceo small; variables chac fie in che 

database are beins scanned. 



Call Notes: 
1 



You have an unspecified IPC error. 



It is raster if the variables you want to access are already listed in the import lisc 
(Refer to che IMPORT call.) 

2. All the specified variables are scanned every half-second. You can pick up chose 
with changes greater than or eaual to the delta value wich a DOCHNG or 
OMREAD. ' 

3. Unlike the C call, which has boch optimized and unoprimized versions, chis call is 
unoprimized. This saves space by using che Object Managers address cable. This 
table is used by many functions wichin che local scacion. Your variable addresses are 
found and added each rime you open the list. 

4. Use the openid when you issue the OMCLOS call. 

5. It is imperative that the lists be closed before any exit from che program. 
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6 A OMREAD - Read Values From Opened list 

The OMREAD call reads variables from che Use opened with che OMOPEN call. This call 
allows you to read all or any pan of che list. You can read parts of che lisc in any order. This 
call is asynchronous; ic returns co your cask as soon as ic has been initiated. You must check 
che status in che value scructure co see if it completed. 
Format: 



X = OMREAD {<openic>,<nimvar>,<incex>,<st:at:us>, <reacva>) 

integer*2 
integar'2 
integer 



OMREAD 

cpenid, nunivar, index (y) , scatus(y) 
raacva 



Where: 
openid 
nuravar 
index (y) 

status (y) 
readva (y) 



Return Codes: 

OM_SUCCESS 

ESECURZ 

EMOTOPENED 

EREAD 

ECONNBAD 

ESCANEuL 



The openid returned by the OMOPEN call 
The number of entries to be read. 

Where x = numvar; the entry you wish to read from the list. If numvar is 
not suecified the default is to read the entire list. 
An array of read scacuses for each encxy in che lisc. 

An array of values for each encry in che list, readva(y) muse be declared in 
four bytes or Soaring point, even if che value is characcer daca cype. 

Example of a mixed variable cype list: 
character** charva (y) 
integer ival (y) 

real readva (y) 

equivalence (charva, ival, readva) 



The list has been read. 

Actempt co open a secured variable. 

Lisc 'is noc opened (or bad om_descripcor). 

The OMOPEN all was sec for wrice only. 

Unable co connecr co remote scacion. 

Lisc open, local scanner database coo small; variables chat fic in che dacabase 
are being scanned. 



Call Noces: 

1. For mulciple errors, che return code shows only one. EREAD ERROR, is super- 
ceded by ESCANFUL, which is superceded by ECONNBAD. 

2. To only read pare of che lisc. you can specify che order. If you read che whole lisc, ic 
reads in ascending order. 
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3. If one of chc stacus values is zero, chat variable has noc been read (or perhaps 
scanned) ycr, or there is a problem such as bad data cype or variable noc found. 
Check for an error return. In an/ case, uval does noc contain a legitimate value. 
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6.5 OMWRIT - Write Values to Opened List 

The OMWRTT 'call writes variables co the array opened wich chc OMOPENczll This call 
allows you co write all or any part of the array. You can write parts of che array in any order. 
This call is asynchronous; it returns to your task as soon as it has been initiated. You must 
check status to see if it completed. 
Format: 



X = OMWRIT 

integer 
integer 
integer 
integer 
integer 
integer 

Where: 
openid 
nuirtvar 
index (y) 

status (y) 
writva (y) 



Return Codes: 

OM_SUCCESS 

ESZCURE 

ENOTOPENED 

EWRITEZRROR 

EWRITE 

ECON*MBAD 

ECMSIZE 

EWAIT 

ESTATION 

ENOSPACS 



( <openid>, <nurnvar>, <incex>, <scacus>, <writva>} 
"2 OMWRIT 
"2 apenid 
* 2 nunvar 
*2 index(y) 
*2 status (y) 

writva(y) 



The openid returned by the OMOPEN call. 
The number of entries to be written. 

Where x = nusivar; the entry you wish to write to the list. If numvar is no'c 
specified the default is to write the entire list in sequential order. 

An array of write statuses for each entry in che list. 

An array of values for each entry in the list, writva (y) must be declared in 
four bytes or floating point, even if the value is character data type. 

Example of a mixed variable type list: 
character* 4 charva (y) 
integer ivai (y) 
real writva (y) 

equivalence (charva, ival, writva) 

The list has been written. 

Attempt to write a secured variable. 

List is not opened (or bad om_descriptor). 

One or more variables inaccessible (check scacuses). 

The openid indicates a read-only access. 

Unable to connect co remote station. 

Value list is < 1 or larger than opened list. 

Remoce scanner(s) haven't updated the list objects. 

All remote stacions haven'c responded. 

Cannot allocace message space for remote wrice. 



(ji> I 
Section 6. FORTRAN Functions to Access/Update Sets of Variables 801 938C - October 3 1 . 1 995 

SIPCRST You have an unspecified IPC error. 

Call Notes: 

1. If you only write parr of the Use you can specify che order by index number. If you 
wrire ir all, it wrires in ascending order regardless of index numbers. 

2. If one of rhe srarus values is zero, rhar variable has no c been read (or perhaps 
scanned) yer, or rhar rhere is a problem such as bad data rype or variable noc 
found. Check for an error return. In any case, aval does noc concam a legitimate 
value. 
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7. FORTRAN Functions to Locate 
and Catalog Objects 

Locating an object means getting its address. Cataloging means installing or removing objeczs 
from the object directory or the import list 

The object directory contains all the shared objects creaced by che tasks in che local scacion. 

The import list contains the names of all data objects that tasks in the local station want to 
import from remote stations. Listed with each name is an index value in to the, address table, 
w hich c ontains the address of the named object. 

FORTRAN Object Manager programs for the AP10/AP20 I/A Series stations use a 16-bit, 
integer*2 for object values. The format for each function described below uses the inter*2 for 
object values. 

FORTRAN Object Manager programs for the 50 Series Application programs must adhere co 
the following conventions: 

♦ All integers must be either INTEGER or INTEGERS (not INTEGER*!). 

♦ Access to OM Control and I/O BOOLEAN Variables must be made through the 
50 Series FORTRAN compiler type : BYTE. 

The FORTRAN functions to locate and catalog objects ar * listed in chis Section in alphabeti- 
cal order and summarized in Table 7-1 . 

J Table 7-1. FORTRAN Functions to Locate a7id Catalog Objects 



Paragraph 
No. 


Call 


Function 


7.1 


IMPORT 


Add object co imporc list 


7.2 


OCREAT 


Add a new objec: to che director/ 


7.3 


ODELET 


Delete from object directory 


7.4 


UNIMPO 


Remove object from import list 
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7.1 IMPORT- Add Object to Import List 



The IMPORT call adds a remocc object co die local stations import list. IMPORT]* synchro- 
nous; your cask suspends until die function is complete. 

Format: 

int IMPORT (<aame>,<objfcyp>) 

character *3 3 rnsxe 

import, objtyp 



integer'2 

Where: 
*name 
ob j_type 

Return Codes: 

CM_SUCCESS 

ESADTYPE 

E3ADNAME 

ENCT FOUND 

ENOSPACS 

ELCCAL 

EIMPEuLL 

EIPCRET 



A pointer to the name of the object to be imported. 

The object's cype, which can be one of the following: VARIABLE, ALIAS, 

PROCESS, or DEVICE. 

The object is now on the import list. 
The specified object type is invalid. 
The specified object name is invalid. 
The object name cannot be found. 
There is a memory allocation error. 
The object you are trying co import is local. 
The import list is too full to add your object. 
An unspecified IPC error. 
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7.2 OCR EAT - Add a New Object to the Directory 

The OCREAThwcuon adds a shared object co chc object director/ and automatically makes 
it global. This function is synchronous; your cask suspends uncil die function completes. 
Format 

X = OCREAT ( <name>, <cb j Cyp>, <varcyp>, <daclar.>) 



US 



in.teger*2 
integer'2 
character*33 



CCREAT 

ohjcyp, vartyp, cat 1 en 
name 



Where: 

name 

objtyp 

vartyp 



datlen 

Re mm Codes: 

0M_SUCCES3 

ESTRLEN 

E3ADTYPE 

E3 AD NAME 

EDUPLICATS 

EOEJPND 

EI PC RET 



The objects name. 

The object's r/pe, which can be one of che following: VARIABLE, ALIAS 
PROCESS, or DEVICE. 

The data type of che objects value,- which can be one of che following 
CHARACTER, INTEGER, FLOAT, or CHARACTER. An alias mSst be 
of variable cypc CHARACTER- varcyp should be null for object types 
PROCESS and DEVICE. 

The character string length for VARIABLE and ALLIS objects. 



The new object is now in the object directory. 

The string length is invalid. 

Either che object or data type is invalid. 

The specified object name is invalid. 

That object name already exists in the directory. 

That object is being created by anocher cask. 

An unspecified IPC error. 
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73 ODELET- Delete From Object Directory 

The ODELETcsll removes an object from che object director/. It is asynchronous; it initiates 
the request then immediately returns control co your task. 

Format: 

X = ODELET <<r.ame>, <ebj cy?>! 

integer*! ODELET 
character w 2 3 name 
integers objtyp 



Where: 
nasie 
obi c yp 

Return Codes: 

OM_SUCCESS 

E3ADNA&1E 

EBADTYPE 

ENCTFOUND 

Call Note: 



The name of the object to be deleted. 

The objects type, which can be one of the following: VARIABLE, ALIAS, 
PROCESS, or DEVICE. 

The request has been initiated successfully. 
The specified object name is invalid. 
The specified object cype is invalid. 
The specified object is not in the directory. 



If a deleted object was connected, it becomes disconnected and any task trying to read 
or write it is notified that it is disconnected (in the status part of the value structure). 
Since there is no error or warning returned when this happens, it is up to you to make 
sure you do not delete the wrong objects. 
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7.4 UNIMPO - Remove Object From Import List 

The UNIMPO function removes an object from die local station's imoort list. This Sanction is 
asynchronous; it initiates the request then immediately returns control co your cask. 
Format: 



X = UNIHFO (<narae>,<cbjfcyp>) 
integer '2 UNIMSO 
character '3 3 name 
intagar-2 objeyp 



Where: 
name 
ob j typ 

. Return Codes: 

OM_ SUCCESS 

E3ADTYPE 

E3ADNAM2 



The name of chc object co be removed. 

The objects cype, which can be one of che following VARI^BtE ALIAS 
PROCESS, or DEVICE. 



The object was successfully removed. 
The specified object cype is invalid. 
The specified objece name is invalid. 
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Appendix A. OM Calls Sample 
Programs 



A.I OM Program Creates and Initializes Variables 

Sine luce <scdio .h> 
^include <fox/om_user .h> 
^include <f ox/om_ecode.h> 

main() 
£ 

float value = 0.0; 

unsigned inc status = FLOAT; 

int static cata_len; 

dataller* = 4; 

rtn = obj_create rCMFlJTIl_?NT- , VARIABLE, FLOAT) ; 

rtn = setval ( M CM?1_TI1 — PNT" , VARIABLE, 0 , lvalue, &st a tus , &data_ler.) ; 
printf ("RTN = %d\n",rtn); 

rtn = obj_create( "OI?l_TI2_?NT rt , VARI A3LE , FLOAT } ; 

rtn = satval( - CMPl_TI2_P*rr w ,VARIA3LE, 0, lvalue, Sstatus, &cata_len) ; 
printf ("RTN = %d\n-,rtn); 

rtn = ob j_create ( "CM?1_TI3_?NT" , VARIA3LE, FLOAT) ; 

rtn = setval { "CMP1_TI3_PNT" , VARIABLE, 0, & value, ^status , &cata_ien) ; 
printf ("RTN = %d\n",rtn); 

rtn = ob j_creata("CMPlJrI4_PNT ,, , VARIABLE, FLOAT) ; 

rtn = setval ( "CM?l_TI4_PNT rt , VARIABLE, 0 , & value, ^status , Sedata_len) ; 
printf ( *RTN = %d\n",rtn) ; 

rtn = obj_creata{"CMP2_FCl_MEAS" , VARIABLE, FLOAT) ; 

rtn =setval ( "CM?2_FC1_MEAS M , VARI A3LE, 0 , lvalue, is :a:us , tcata.ler.) ; 
printf ( " RTN = %d\n",rtn); 

rtn = obj_create("CM?2_FC2_MEAS-, VARIABLE, FLOAT) ; 

rtn =setval ( "CM?2_FC2_MEAS" , VARIABLE, 0, & value, is cat us, ica ta_len) ; 
print £ ( " RTN = %d\n M ,rtn) ; 

rtn = obj_create (* CMP 2 _FC 3 JtfEAS", VARIABLE, FLOAT) ; 

rtn =setval ( ,, CMP2_FC3_MEAS " , VARIABLE, 0, lvalue, ^status, &cata_ler.) ; 

printf ("RTN = %d\n",rtn); " 

rtn = obj_create( ■ , CM?2_FC4_MZAS'* , VARIABLE, FLOAT) ; 

rtn =setval ( "CM?2_FC4_MEAS" , VARIABLE, 0, fcvalue, istatus, icataj.erj ; - 
print £ ( M rtn = %d\n",rtn) ; 

rtn = obj_create( H CM?3_FZ01_?.Itfl'' , VARIABLE, FLOAT) ; 
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rtn=setval ( ,, CMP3_FZ01_RINI" , VARIABLE, 0 , lvalue, fcscatus , fcca taller.) ; 
print f ( " RTN = %d\n tt ,rtn); 

rtn = ob j_create("CM?3_F201_RlN2-, VARIABLE, FLOAT ) ; 

rcn=satval { "CMP3_FZ01_RIM2 " , VARIABLE, 0 , ivaiua, iscatus , £data_ler:) ; 

printfCRTN = %d\n" f rtn) ; 

rtn = obj.craata { "CM?3_FZ01_RIN3 " , VARIABLE, FLOAT) ; 

rtn=setval ( "CMP3_FZ01_RIN3 N , VARIABLE, 0 , lvalue , istarus f idaza^len) ; 

print f ( " RTN = %d\nMcn) ; 

r:n = ob j_craate(-CHP3_FZ01_RIN4", VARIABLE, FLOAT) ; 

rtn=satval ( "CM?3_FZ01_RIN4 " r VARIABLE , 0 , fcvalue, &status , idata_ler.) ; 

print f ( W RTN = %d\n" , rtn) ; 

} 

A.2 0M Program Opens Two Lists for Read-s-ancl 
Writes 



£ include <stdio.h> 
^include <f ox/om_usar .h> 
^include <f ox/om_ecoca.h> 



main( ) 
{ 



s truce open_var in_var_list [8] , out_var_list [4] ; 

struct header.node in_ora_dasc, out_om_desc 

struct net_adr in_net_acr_tbl [2 ] , cut_net_acr_tbl; 

int in_open_id, out_oper._id; 

int rtn; 

float deita.teinp, delta_£c, dalta.df; 

struct value *-in_cata_list , *out_data_list , *temp; 

int i; 

celta.temp = 5.0; 
delta.fc = 1.0; 
delta_df = 0.5; 

in.om.desc. task.status » CM.R.ACCESS; 
in_om_desc.net__adr_tbl_?tr = in_net_adr_tbl ; 
in_ora_desc.size_net_adr_tbl = 2; 
in_om_desc.cpe.n_list_ctr = in_var_iist ; 
in_on_desc.size_oceri_lis:: = 8; 

out.om.dasc. task.scatus = CM.W.ACCESS; 
out_om_desc . net.adr_tbL^tr= &cur_net_acr_tcl ; 



f; h , 
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cut_cm_desc.size_net_adr_tbi = 1; 
out_om_desc. oper._lisc _ctr = cut_var_lisc ; 
ou t_ora_desc.size_ocer._iisc = 4; 

strcpy(in_var_list(0] .name, "CM?1_TI1_?N?" ) ; 
in.var.lisCCOJ.var.casc = NOTIFY; 
in_var_Iist CO] .delta = celta.temp; 

s trcpy ( in_var_l is t [ 1 ] .name, •CM?1_TI2_PNT W ) ; 

in_var_list[l] .var_desc = NOTIFY; 

in_var_list CI] -delta = deita_temp; 

s t r cpy ( i n_var_l i s t [ 2 ] . name , -CMP1_TI3_PNT W ) ; 

in_var_list[2] .var_cesc = NOTIFY; 

in_var_list [2] .delta = delta_temp; 

s t rcpy ( in_var_l is t [ 3 ] .name, "CMP1_TI4_?MT H ) ; 

in_var_lisc[3 ] . varices c = NOTIFY; 

in_var_list C3] .delta = delta_temp; 

st rcpy ( in_var_l is t C 4 ] .name, ■CMP2_FC1_MEAS" ) ; 

in_var_list[4] .var_desc = NOTIFY; 

in_var_listC4] .delta = dalta_fc; 

strcpy(in_var_list[5] .name, "CMP2_FC2 JtfEAS" ) ; 

in_var_lisc[5] .var_desc = NOTIFY; 

in_var_list[5] .delta = delta_fc; 

strcpy(in_var_list [6] .name, "CMP2_FC3_M£AS" ) ; 

in_var_list[6] . varices c = NOTIFY; 

in_var_list[S] .delta = delta_£c; 

st rcpy ( in_var_list [7 ] .name, "CMP2_FC4_MEAS" } ; 

in_var_list[7] .var_desc = NOTIFY; 

ia-var_list[7] .delta = delta.fc; 

strcpy(out_var_list [0] .name, "CMP3_FZ01_RIN1" ) 
out.var.list CO] .var.desc = NOTIFY; 
out_var_list[0] .delta = delta_df; 
s trcpy (out_var_list [1 ] .name, -CMP3_FZ01_RIN2 • } 
out_var_list [1] . varices c = NOTIFY; 
out_var_list [1] .delta = delta_d£; 
strcpy( ou t_var_list [2] .name, N CM?3_?Z01_R:N3 " ) 
cut_var.list C2] .var_desc = NOTIFY; 
out_var_list [2] .delta = ceita_c£; 
strcpy (ouc_var_list [3 ] .name, "CM?3_FZ0i_R:M4" ) 
out_var_list C3 ] .var_desc = NOTIFY; 
out_var_listC3] .delta = dalta.df; 

rtn = omopen (&in_ ora.cesc, Sein_open_id) ; 
Printf (-Return = %d\n H ,rtn); 
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rtn = omopen(£ouc_om_dasc, &cut_ocen_id) ; 



if ( (in_data_list = (struct value *)v_variisc (8)) == NULL) 
( 

print f ("Can't allocate space \n"); 

omclosa ( in_cper._ic, &in_om_desc, in_var_lisc, 



in_ne t_acr_t b 1 ) ; 
omclosa (cut_open_id, &out_om_desc, out_var_iist , 



&out_r.ec_adr_tbi) ; 
exit(O) ; 

} 

sleep ( 1) ? 

if ( (rtn = omread(in_open_id,8, in_data_list) ) 1= OM_SUCC£SS) 
{ 

print f ("Return = %d\n" , rtn" ) ; 

omclosa ( in_oper._id, Scin_om_desc, in_var_list , 



in_net_adr_tbl) ; 
omclosa (out_open_id, &out_om_desc, out_var_iist, 

&out_net_adr_tbi) ; 
exit{0) 



for (1 = 0; i<3; 
{ 

printf ("Variable %d = %f \n" ,i, in_data_list->uval . f point) ; 

in_data_list^; 

} 

if ( (out_data_list = (struct value *)v_yarlist (4)) == NULL) 



printf ("Can' t allocate space \n"); 

omclose ( in_open_id, &in_om_desc, in_var_lisc, 

in_net_adr_tbl) ; 
omclose (out_open_id, &out_om_desc , out_var_list , 

&out_net_adr_tbl) ; 
exit (0) ; 



} 

temp = out_data_list; 

for (i = 0; i < 4; i++] 
C 

temp->index = i; 
tem?->status = FLOAT; 
temp->uval . f point = 5.0; 



printf ( "Return = %d\n" ,rtn) ; 
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tenip**; 
} 

if((rtn = cmwrita(out_ocen_id, 4, out_daca_lis::) ) 
1= CM.SUCCZSS) 

c 

princf ( "Racum = %c\n ,f rcn); 

for(i=0; i<4;i++) 
{ 

princf ( "status = %u\n'\ out_daca_list-> 

status) ; 
cut_data_lisC++ ; 
} 

omclose ( in_open_id, fciri_ora_desc, in_var_lisc, 

_in_net_adr_tbl) ; 
omclose (out_open_id, &out_om_dasc, out_yar_iisC , 

&out_net_adr_tbl) ; — 
exit(O); 

} 



omclose ( in_cpen_id, &in_orri_dasc, in_var_list , in_nat_adr_tbl ) ; 
omclose (out_operi_id, &out_om_dasc, cut_var_list , £ouc_ neC_adr_Cbl] 
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Appendix B. OM Error Codes 



Code 


Message 


Code 


Message 


0 


Call executed successfully 


-30 


Dqchange queue is empcy 


-1 


Not found 


-31 


No address cable 


-2 


Bad data, type 


-32 


Unable co gee a queue for nocificacion 


-3 


Variable is secured 


-33 


Unable co send open requests 


-4 


List not opened 


-34 


Address cable full 


-5 


Error reading lisc 


-35 


Noc accivaced wich IPC 


-6 


List wricc only 


-36 


Error creacing conneccion cable 


.7 

/ 


1.15c reao. omy 


J / 


Error c-£5Tin<y f^ismnnpT ^ ] <» 


-8 


i-xiur writing use 




Error creatine nosi id rinl*» 


_g 

y 


ivicmory allocation error 






-10 


v Aiiau ic aireaay erusts 




Scanner db full 


-11 




-41 


Error returned from IPC 


-12 


^Ia.rfi«» tnv3itrl 


-42 


Remoce scanner has noc resoonded 

4. 


-13 


\Xfarn I n tr all rlis n nnr rerurn^d 


-43 


Remcce scacion has noc responded 


-14 


Strin? lentrth Is invalid 


-44 


Anocher object of this name is pending 
creation 


-15 


List already opened 


-45 


No confirmation 


-16 


Bad variable lisc poincer 


-46 


Error creacing queue for OM VENIX 
cask 


-17 


Bad address cable poincer 


-47 


Error creacing OM scanner cask 


-18 


List has connection problems 


-48 


Error creacing OM VENIX cask 


-19 


Dqchange queue noc empcy 


-49 


Error creacing OM server cask 


-20 


Objecc type has no value record 


-50 


Received fab ore 


-21 


Value record corruoced 


-51 


Invalid lisc size 


-22 


Error creacing import lisc 


•52 


Error creacing reconnect queue 


-23 


Error creacing objecc directory 


-53 


Invalid users address cable size 


-24 


Error creacing address cable 


-54 


Error creacing OM reconnect cask 


-25 


Error creacing scanner db 






-2(3 


Imporc lisc full 






-27 


Error creacing dqchange queue 
cable 






-28 


Error creacing a queue 






-29 


Invalid lisc size 
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Appendix C. OM Calls 

C.I OM C Calls Summary 



dqchange 


int dqchange (<pid>, <suscer.d> / <cpar._id>, j 
<siza_lisc>, <value_list>, <rec siza>) 


dqlist 


j inc dqlist (<pid>,<suspend>,<oper._id>,<siza_lisc>, 
J <value_list>, <ret_siza>) 


^ e — w ax 


int getvai {<name>, <ob j_type>, <ir»pcrt> / <value> / 


getval_list 


<vaiue> # <status>, <data_len>, <cpen_id>, <cv_incax>) ! 


global_find 




import 


int import (<naroe>, <obj_type>) 




int obj_create (<name>, <obj_type>, <var_typa>, 
<str_len>) 


Obi Gpl pha 


int ob j_delete (<name>, <ob j typa>) 


°oj_roulti_create 


int obj_multi_create (<ob j_pcr>, <num_abjects>) 


omclose 


int omclose (<open_id>, <header>, <var_list>, 
<addr_tbl>) 


omopen 


int omopen (<om_descriptor>, <cpen_id>) 


omread 


int. omread (<omopen_id>,<size_list>,<var_list>) 


orawrite 


int omwrita(<omopen_id>,<size_list>, <var_list>) j 


omw2rstat 


int omwrstat (<oraopen_id>, <size list>,<var list>) | 


oro_getval 


int om_getval (<name>, <obj_type>,<import>,<valua>, I 
<status>,<data_len>, <psap_p tr>) 1 


ora_setval 


int om_setval (<name>, <ob j_type>, <import>, <value>, i 
<status>,<data_len>, <psap_ptr>) | 


onuset_confirm 


inc om_set_conf irm(<name>, <obj_type>, <import>, 
<value>, <status>, <data_len>, <psa?_ptr>) 


set_cnf_list 


int set_cnf_list (<name>, <obj_cype>, <imporc>, j 
<value>, <status>, <data_len>, <ccen_id>, <cv_indax>) j 


set_confirm 


inc sac_conf irm(<name>, <cb j_type>, <i:nport>, j 
<value>, <status>, <data_ler.>} : 


setval 


inc setval (<name>, <obj_type>, <irnccr::>, <value>, ! 
<stat:us>, <data_len>) j 


secval^iist 


inc secvai_list (<name>, <cbj_type>, <imporc>, ; 
<value>, <scatus>, <daca_lan>, <oce:-_ic>, <ov_incax>) : 


s:_orassc_con£ irm 


int sc_omsec_conf irm(<na:na>, <cbj_r/pe>, <i;nporc>, j 
<value>, <staus>, <daca_lari>, <psac_?cr>, <sc_daza>, 1 
<sc_mas!<>, <st_only>, <appi_work>) 1 
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! sc_cm_satval 

1 


int st_ora_satval (<nar:a>,<cbj_typa>, <import>, 
<value>,<staus>, <data_Lan>, <psap_ptr>, <st_data>, 
<stjzia.sk>, <st_only>, <a?pl_war5c>l 


j sc_satcnf 

! 

• 


int st_satcnf (<name>, <cbj_cype>, <import>, <valus>, 
<scacus>, <data_lar.>, <sc_cata>, <3i_T fc ask> / <st_oniy>, 
<ac?l_wor;<>) 


st_satlis::_canf irsi 


int' st_satlist_ccnfirn(<na^.a>, <obj_typa>, <import>, 
<value>, <status>, <daza_lar i > < <cpan_ic>, <ov_indax>, 
<st_data>, <st_mask>, <st_ar.iy^, <appl_wcrk>) 


sc_sat_lisc 


int st_set_list (<naina>, <obj_typa>, <iraport>, 
<valua>, <status>,<data_lar.>, <cpa::_id>, <ov_index>, 
<st_data>, <st_mask>, <st_oniy>, <appi_work> 


st_satval 


int st_satval (<name>, <obj_typa>, <iraporz>, <valua>, 
<status>, <data_lan>, <st_data>, <sz jm.sk> , <s t_only>, 
— frapp l_wo r k> ) 


unimport 


int unimport (<name>, <obj_typa>) 



C.2 OM FORTRAN Calls 



DQCKNG 


X = DQCHNG (<fIag>,<openid>,<csiza>,<qindex>, 
<qstat>,<value>, <rqsiza>) 


GETVAL 


X ■ GETVAL (<name> / <objtyp> / <iniport>, <value>, 
<status>, datlen) 


IMPORT 


int IMPORT (<name>, <ob j typ>) 


GCREAT 


X = OCREAT (<name> / <objtyp> / <varcyp>, <datlen>) 


ODELET 


X = ODELET (<naiae> / <abj typ>) 


OMCLOS 


X = OMCLOS (<nuiavar>,<opar.id>) 


OMOPEN 


X = OMOPEN {<mmvar>,<naiaa>,<daita>,<notify> # 
<rwaco,<openid>,<scnrat>) 


OMREAD 


X = OMREAD (<openid>,<niCTvar>,<index>,<status>, 
<raadva>) 


OMWRIT 


X ■ OMWRIT {<cpanid>,<nurnvar>,<index>,<status>, 
<writva>) 


SETCON 


X = SETCON (<name>, <ob j typ>, < import >, <valua> , 
<status>, <datlan>) 


SETVAL 


X = SETVAL (<name>, <obj typ>, <i~pcrt> , <value> 1 
<status>, <datlan>) 


UNIMPO 


X = UNIMPO (<naine>, <obj typ>) 



c 

Index 



c 

Change Queues 48 
D 

data types 1 
dqchange 46 
DQCHNG 89 
dqlxsc51 

C 

GETVAL 80 
getval 10 
gecvaljist 12 
globaI_find 2, 72 



I IMPORT 100 
. import 73 

import list 2, 71 

import table 7 

O 

obj_create 74 

obj_del«e 75 

obj_muIci_create 76 

object directory 7 

Object Manager Address Table 7 

OCREAT101 

ODELET102 

om_gcrvaJ 14 

om_header_node structure 3 
om_sct_confirm 16 
om_setval 18 
OMCLOS 91 
omclose 54, 57 
OMOPEN 3, 92 
omopen 55, 56 
Omopen Connections 60 
Omopen Server Broadcasc 60 
Omopen Server Re cur n 61 
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OMREAD 94 
omread 62 
OMWRTT 96 
omwrite 64, 67 
open pomes databas 6 

paramerer cable 4 
process variables 2 
process-control objects 1 

5 

scanner connection table 8 
scanner database 6 
server connection cable 8 
set_cnf_list 22 
serjronSrm 20 
sct_confirm_list 39 
SETCON 82 
SETVAL84 
serval 24, 43 
secval_lisc 26 
shared objects 1 
st_om_serval 3 1 
st_omset_confirm 28 
sc_set_lisc 40 
st_setcnf 34 
st_sedisc_confirm 37 

U 

UNIMPO 103 
un import 78 



V 

variable scan rate 3 



